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Alphabetic Reference 


Introduction 


The Microsoft® Windows™ 3.1 operating system is a single-user system for per- 
sonal computers. Applications that run with this operating system use functions in 
the Windows applications programming interface (API). This manual describes 
the API functions in alphabetic order, including each function’s purpose, the ver- 
sion of Windows in which it first appeared, and the function’s syntax, parameters, 
and possible return values. Many function descriptions also contain additional in- 
formation and simple code examples that illustrate how the function can be used to 
carry out simple tasks. | 


How to Use This Manual 


For most of the functions described in this manual, the syntax is given in C- 
language format. In your C-language source files, the function name must be 
spelled exactly as given in syntax and the parameters must be used in the order 
given in syntax. 


The Windows API uses many types, structures, and constants that are not part of 
standard C language. These items, designed for Windows, are defined in the 
Windows C-language header files. Although there are many Windows header 
files, the majority of API functions, structures, and messages are defined in the 
WINDOWS.H header file. You can use these items in your Windows application | 
by placing an #include directive specifying WINDOWS.H at the beginning of 
your C-language source file. 


In this manual, if a function is not defined in WINDOWS.H, its appropriate header — 
file is included in the first line of syntax. If no header file is listed, you can assume 
the function is defined in WINDOWS.H. 


Note You will find a list of the appropriate module and library for each Windows 
function in the Microsoft Windows Programmer’s Reference, Volume 1. A list of 
the types used in the Windows API, with a brief description of each, is provided in 
the Microsoft Windows Programmer’s Reference, Volume 3. 
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Document Conventions 


The following conventions are used throughout this manual to define syntax: 


Convention Meaning 


Bold text Denotes a term or character to be typed literally, such as a resource- 
definition statement or function name (MENU or CreateWindow), 
a Microsoft MS-DOS® command, or a command-line option 
(/nod). You must type these terms exactly as shown. 


Italic text Denotes a placeholder or variable: You must provide the actual 
value. For example, the statement SetCursorPos(X, Y) requires you 
to substitute values for the X and Y parameters. 


[ ] Enclose optional parameters. 

| Separates an either/or choice. 

oe Specifies that the preceding item may be repeated. 
BEGIN Represents an omitted portion of a sample application. 


END 
In addition, certain text conventions are used to help you understand this material: 


Convention Meaning 
SMALL CAPITALS Indicate the names of keys, key sequences, and key 
combinations—for example, ALT+SPACEBAR. 


FULL CAPITALS Indicate filenames and paths, most type and structure names 
(which are also bold), and constants. 


monospace ‘ Sets off code examples and shows syntax spacing. 


AbortProc 1 


AbortDoc ar, | EXE 


int AbortDoc(hdc) 
HDC hdc; /* handle of device context */, 


The AbortDoc function terminates the current print job and erases everything 
drawn since the last call to the StartDoc function. This function replaces the 
ABORTDOC printer escape for Windows version 3.1. 


Parameters hdc 
Identifies the device context for the print job. 


Return Value The return value is greater than or equal to zero if the function is successful. Other- 
_ wise, it is less than zero. 


Comments Applications should call the AbortDoc function to terminate a print job because of 
- an error or if the user chooses to cancel the job. To end a successiul print job, an. 
application should use the EndDoc function. 


If Print Manager was used to start the print job, calling the AbortDoc function 
erases the entire spool job—the printer receives nothing. If Print Manager was not — 
used to start the print job, the data may have been sent to the printer before Abort- 
Doc was called. In this case, the printer driver would have reset the printer (when 
possible) and closed the print Jone | 


See Also ~ EndDoc, SetAbortProc, StartDoc 


AbortProc % [3.1 | 


BOOL CALLBACK AbortProc(hdc, error) 
HDC hdc; /* handle of device context **/ 
interror; — /* error value | 


The AbortProc function is an application-defined callback function that is called 
when a print job is to be canceled during spooling. 


Parameters hdc | 
Identifies the device context. 


error | 
Specifies whether an error has occurred. This parameter is zero if no error has — 
occurred; it is SP_LOUTOFDISK if Print Manager is currently out of disk space 


2 __AccessResource 


and more disk space will become available if the application waits. If this 
parameter is SP_OUTOFDISK, the application need not cancel the print job. If 
it does not cancel the job, it must yield to Print Manager by calling the Peek- 
Message or GetMessage function. 


Return Value The callback function should return TRUE to continue the print job or FALSE to 
cancel the print job. | 


Comments An application installs this callback function by calling the SetAbortProc func- 

| tion. AbortProc is a placeholder for the application-defined function name. The 
actual name must be exported by including it in an EXPORTS statement in the ap- 
plication’s module-definition file. 


See Also GetMessage, PeekMessage, SetAbortProc 


AccessResource [ax] 


int AccessResource(hinst, hrsrc) 
HINSTANCE hinst; /* handle of module with resource */ 
HRSRC hrsrc; _ /* handle of resource | i ae 


The AccessResource function opens the given executable file and moves the file © 
pointer to the beginning of the given resource. 


Parameters hinst 7 
Identifies the instance of the module whose executable file contains the re- 
source. 


hrsrc 
Identifies the desired resource. This handle should be created by using the 
FindResource function. 


Return Value The return value is the handle of the resource file if the function is successful. 
Otherwise, it is —1. 


Comments — The AccessRisoiiree function supplies an MS-DOS file handle that can be used in 
| subsequent file-read calls to load the resource. The file is opened for reading only. 


Applications that use this function must close the resource file by calling the 
_Iclose function after reading the resource. AccessResource can exhaust available 
MS-DOS file handles and cause errors if the opened file is not closed after the re- 
_ source is accessed. 


AddAtom 3 


Tn general, the LoadResource and LockResource functions are preferred. These 


See Also 


AddAtom 


functions will access the resource more quickly if several resources are being read, 
because Windows maintains a file-handle cache for accessing executable files. 
However, each call to AccessResource requires that a new handle be opened to 
the executable file. 


You should not use AccessResource to access executable files that are installed in 
ROM on a ROM-based system, since there are no disk files associated with the ex- 
ecutable file; in such a case, a file handle cannot be returned. 


FindResource, _Iclose, LoadResource, LockResource 


Exa 


ATOM AddAtom(lpszName) 


LPCSTR /pszName; 


Parameters 
Return Value 


Comments 


[* aadiess of string toadd—s */ 


The AddAtom function adds a character string to the local atom table and returns 
a unique value identifying the string. 


IpszName , 
Points to the null- terminated character string to be added to the table. 


The return value erences the newly created atom if the function is successful. 
- Otherwise, itis zero. 


The AddAtom function stores no more than one copy of a given string in the atom 
table. If the string is already in the table, the function returns the existing atom 


_ value and increments (increases by one) the string’s reference count. 


Example > 


The MAKEINTATOM macro can be used to convert a word value into a string 
that can be added to the atom table by using the AddAtom function. 


T he atom values returned by AddAtom are in the range 0xC000 through OxFFFF. 


Atoms are.case- insensitive. 


The following cxample: uses the AddAtom function to add the string “This is an 


atom”’ to the local atom table: 


4 AddFontResource 


ATOM at; 
char szMsg[80]; 


= AddAtom("This is an atom"); 


if (at == 0) 
MessageBox(hwnd, "AddAtom failed", "", MB_ICONSTOP); 
else { | 
wsprintf(szMsg, “AddAtom returned 4u", at); 
MessageBox(hwnd, szMsg, "", MB OK); 
} 
See Also DeleteAtom, FindAtom, GetAtomName 


AddFontResource — fax] 


int AddFontResource(IpszFilename) 
LPCSTR [pszFilename; /* address of filename a 


The AddFontResource function adds a font resource to the Windows font table. 
Any application can then use the font. 


Parameters lpszFilename | 
7 Points to a character string that names the font resource file or that contains a 
handle of a loaded module. If this parameter points to a font resource filename, 
it must be a valid MS-DOS filename, including an extension, and the string 
must be null-terminated. The system passes this string to the LoadLibrary 
function if the font resource must be loaded. 


Return Value The return value specifies the number of fonts added if the function is successful. 
Otherwise, it is zero. 


Comments Any application that adds or removes fonts from the Windows font table should 
send a WM_FONTCHANGE message to all top-level windows in the system PY 
using the SendMessage function with the hwnd parameter set to OXFFFF. 


When font resources added by using AddFontResource are no longer needed, 
you should remove them by using the RemoveFontResource function. 


Example The following example uses the AddFontResource function to add a font re- 
source from a file, notifies other applications by using the SendMessage function, 
then removes the font resource by using the RemoveF ontResource function: 


AdjustWindowRect 


AddFontResource("fontres.fon"); 
SendMessage(HWND_ BROADCAST, WM_FONTCHANGE, @, 0); 


. /* Work with the font. */ 
if (RemoveFontResource("fontres.fon")) { 
SendMessage(HWND_ BROADCAST, WM _FONTCHANGE, @, Q); 


return TRUE; 


} 
else 


return FALSE; 


See Also LoadLibrary, RemoveFontResource, SendMessage 


AdjustWindowRect wn ee ry 


void Adjust WindowRect(Iprc, dwStyle, fMenu) 


RECT FAR* [prc;__—_—s/* address of client-rectangle structure */ 
DWORD dwSvple; /* window styles | **/ 
BOOL fMenu; /* menu-present flag | *f: 


The AdjustWindowRect function computes the required size of the window 

rectangle based on the desired client-rectangle size. The window rectangle can 

then be passed to the CreateWindow function to create a window whose client 
area is the desired size. 7 


Parameters [pre — 
Points toa RECT structure that contains the coordinates of the client rectangle. 
The RECT structure has the following form: 


typedef struct tagRECT { /* ro */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 3 

dwStyle 
been the window styles of the window whose client rectangle is to be con- — 
verted. | - | 

JMenu 


Specifies whether ihe window has a menu. 


6 AdjustWindowRectEx 


Return Value 


Comments 


See Also 


AdjustWindowRectEx 


This function does not return a value. 


A client rectangle is the smallest rectangle that completely encloses a client area. 
A window rectangle is the smallest rectangle that completely encloses the window. 


AdjustWindowRect does not take titles and borders into account when comput- 
ing the size of the client area. For window styles that include titles and borders, ap- 
plications must add the title and border sizes after calling AdjustWindowRect. 
This function also does not take the extra rows into account when a menu bar 
wraps to two or more rows. 


AdjustWindowRectEx, CreateWindowEx 


void AdjustWindowRectEx(Iprc, dwStyle, fMenu, dwExStyle) 


RECT FAR* Iprc; 
DWORD dwSple; 
BOOL /{Menu; 
DWORD dwExStyle; 


Parameters 


/* address of client-rectangle structure oy 
/* window styles **/ 
/* menu-present flag cl 
/* extended style | * / 


The AdjustWindowRectEx function computes the required size of the rectangle 
of a window with extended style based on the desired client-rectangle size. The 
window rectangle can then be passed to the CreateWindowEx function to create 
a window whose client area is the desired size. 


lpre | 
Points to a RECT structure that contains the coordinates of the client rectangle. 
The RECT structure has the following form: 


typedef struct tagRECT { /* reo x*/ 
int left; 
int top; 
int right; 
int bottom; 
+. RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 7 


dwStyle 3 
Specifies the window styles of the window whose client rectangle is to be con- 
verted. 7 


AllocDiskSpace 7 


fMenu 


Specifies whether the window has a menu. 


dwExStyle | 
Specifies the extended style of the window being created. 


Return Value This function does not return a value. 


Comments A client rectangle is the smallest rectangle that completely encloses a client area. 
A window rectangle is the smallest rectangle that completely encloses the window. 


AdjustWindowRectEx does not take titles and borders into account when com- 
puting the size of the client area. For window styles that include titles and borders, 
applications must add the title and border sizes after calling AdjustWindow- 
RectEx. This function also does not take the extra rows into account when a menu 
bar wraps to two or more rows. 


See Also Adjust WindowRect, CreateWindowEx 


AllocDiskSpace gee oa 
#include <stress.h> | | oe ee 


int AllocDiskSpace(/Left, uDrive) 
long /Left; /* number of bytes left available */ 
UINT wuDrive; /* disk partition | 
| The AllocDiskSpace function creates a file that is large enough to ensure that the 


specified amount of space or less is available on the specified disk partition. The 
file, called STRESS.EAT, is created in the root directory of the disk partition. — 


If STRESS.EAT already exists when AllocDiskSpace is called, the function de- 
letes it and creates a new one. 


Parameters Left — en. 
: Specifies the number of bytes to leave available on the disk. 
uDrive : ee : | 
Specifies the disk partition on which to create the STRESS.EAT file. This 
parameter must be one of the following values: 


8 AllocDStoCSAlias 


Value Meaning 


EDS_WIN Creates the file on the Windows partition. 
EDS_CUR Creates the file on the current partition. 
EDS_TEMP Creates the file on the partition that contains the TEMP directory. 


Return Value The return value is greater than zero if the function is successful; it is zero if the 
function could not create a file; or it is —1 if at least one of the parameters is in- 
valid. 

Comments In two situations, the amount of free space left on the disk may be less than the 


number of bytes specified in the /Left parameter: when the amount of free space 
on the disk is less than the number in /Left when an application calls Alloc- 
DiskSpace, or when the value of /Left is not an exact multiple of the disk cluster 
Size. 


The UnAllocDiskSpace function deletes the file created by AllocDiskSpace. 


See Also UnAllocDiskSpace 


AllocDStoCSAlias 


UINT AllocDStoCSAlias(uSelector) 
UINT uSelector; /* data-segment selector | 


The AllocDStoCSAlias function accepts a data-segment selector and returns a 
code-segment selector that can be used to execute code in the data segment. 


Parameters uSelector 
Specifies the data-segment selector. 


Return Value The return value is the code-segment selector corresponding to the data-segment 
selector if the function is successful. Otherwise, it is zero. 


- Comments The application should not free the new selector by calling the FreeSelector func- 
| tion. Windows will free the selector when the application terminates. 


In protected mode, attempting to execute code directly in a data segment will 
cause a general-protection violation. AllocDStoCSAlias allows an application to 
execute code that the application had created in its own stack segment. 


See Also 


AllocFileHandles 


_ #include <stress.h> 


AllocFileHandles 9 


Windows does not track segment movements. Consequently, the data segment 
must be fixed and nondiscardable; otherwise, the data segment might move, invali- 
dating the code-segment selector. 


The PrestoChangoSelector function provides another method of obtaining a code 
selector corresponding to a data selector. 


An application should not use this function unless it is absolutely necessary, since 


its use violates preferred Windows programming practices. 


FreeSelector, PrestoChangoSelector 


int AllocFileHandles(Le/t) | 
int Left; —_/* number of file handles to leave available = */ 


Parameters 


Return Value 


~ Comments — 


See Also 


The AllocFileHandles function allocates file handles until only the specified num- 
ber of file handles is available to the current instance of the application. If this or a 
smaller number of handles is available when an application ae AllocFile- 


- Handles, the function returns immediately. 


Before siloatne new handles, this function frees any handles previously allocates 
by AllocFileHandles. | 


_ Left 


Specifies the number of file handles to leave available. 


The return value is greater than zero if AllocFileHandles successfully allocates at 
least one file handle. The return value is zero if fewer than the specified number of 
file handles were available when the application called AllocFileHandles The re- 
turn value i is —1 if the tet parameter is negate. 


AllocFileHandles will not allocate more than 256 file handles, regardless of the 
number available to the application. | 


: The UnAllocFileHandles function frees all file handles eteviotisly allocated by 


AllocFileHandles. 


UnAllocFileHandles 


10 AllocGDIMem 


AllocGDIMem : e EN 


#include <stress.h> 


BOOL AllocGDIMem(uLef?) 
UINT uLeft; /* number of bytes to leave available sa | 


The AllocGDIMem function allocates memory in the graphics device interface 
(GDI) heap until only the specified number of bytes is available. Before making 
any new memory allocations, this function frees memory previously allocated by — 
AllocGDIMem. 


Parameters uLeft 
Specifies the amount of memory, in bytes, to leave available in the GDI heap. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The FreeAllGDIMem function frees all memory allocated by AlloeGDIMem. 
See Also FreeAllGDIMem 


AllocMem — [3.1 | 
#include <stress.h> | | 


BOOL AllocMem(dwLeft) 
DWORD dwLeft; /*smallest memory allocation */ 


The AllocMem function allocates global memory until only the specified number 
of bytes is available in the global heap. Before making any new memory alloca- 
tions, this function frees memory previously allocated by AllocMem. 


Parameters — dwLeft | 
Specifies the smallest size, in bytes, of memory allocations to make. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The FreeAllMem function frees all memory allocated by AllocMem. 


See Also FreeAllIMem 


AllocSelector 11 


AllocResource [ex] 


HGLOBAL AllocResource(hinst, hrsrc, cbResource) 


HINSTANCE hinst; /* handle of module containing resource ps 
HRSRC hrsrc; /* handle of resource | */ 
DWORD cbResource; /* size to allocate, or zero */ 


Parameters 


Return Value 


See Also 


AllocSelector 


The AllocResource function allocates uninitialized memory for the given resource. 


hinst 
Identifies the instance of the module whose executable file contains the re- 


source. 


hrsrc 
Identifies the desired resource. This handle should have been created by using 
the FindResource function. | 


cbResource 
Specifies the size, in bytes, of the memory object to allocate for the resource. If 


_ this parameter is zero, Windows allocates enough memory for the specified re- 
source. 


The return value is the handle of the global memory object if the function is 
successful. | 


~ FindResource, LoadResource 


UINT AllocSelector(uSelector) 


UINT uSelector; 


Parameters 


/* selector to copy or zero +] 
The AllocSelector function allocates a new selector. 


Do not use this function in an application unless it is absolutely necessary, since | 
its use violates preferred Windows programming practices. | 


uSelector 
Specifies the selector to return. If this parameter specifies a valid selector, the 
function returns a new selector that is an exact copy of the one specified here. If 
this parameter is zero, the function returns a new, uninitialized sector. 


12 AllocUserMem 


Return Value The return value is a selector that is either a copy of an existing selector, or a new, 
| uninitialized selector. Otherwise, the return value is zero. 


Comments The application must free the new selector by calling the FreeSelector function. 


An application can call AllocSelector to allocate a selector that it can pass to the 
PrestoChangoSelector function. 


See Also PrestoChangoSelector 


AllocUserMem : [3.1 | 


#include <stress.h> 


BOOL AllocUserMem(uContig) | 
UINT uContig; —_/* smallest memory allocation =), 


The AllocUserMem function allocates memory in the USER heap until only the 
specified number of bytes is available. Before making any new allocations, this 
function frees memory previously allocated by AllocUserMem. 


Parameters uContig 7 _ 
Specifies the smallest size, in ee of memory allocations to make. 


~ Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The FreeAllUserMem function frees all memory allocated by AllocUserMem. 
See Also  FreeAllUserMem 


AnimatePalette Pee e 


void AnimatePalette(hpal, iStart, cEntries, lppe) 


HPALETTE hpal; _ /* handle of palette | */ 
UINT iStart; | /* first palette entry to animate | 
UINT cEntries; /* number of entries in palette sy 


const PALETTEENTRY FAR* [ppe; /* address of color structure | 


AnimatePalette 13 


The AnimatePalette function replaces entries in the specified logical palette. An 
application does not have to update the client area when it calls AnimatePalette, 
because Windows maps the new entries into the system palette immediately. 


Parameters Ahpal 
Identifies the logical palette. 


iStart 
Specifies the first entry in the palette to be animated. 


cEntries — 
Specifies the number of entries in the palette to be animated. 


lppe | 
Points to the first member of an array of PALETTEENTRY structures. These 
palette entries will replace the palette entries identified by the iStart and 
cEntries parameters. The PALETTEENTRY structure has the following form: 


typedef struct tagPALETTEENTRY { /* pe */ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


Comments | The AnimatePalette function can change an entry in a logical palette only when 
the PC_LRESERVED flag is set in the corresponding palPaletteEntry member of 
the LOGPALETTE structure that defines the current logical palette. 


Example © The following example initializes a LOGPALETTE structure and an array of 
PALETTEENTRY structures, uses the CreatePalette function to retrieve a 
handle of a logical palette, and then uses the AnimatePalette function to map the 
entries into the system palette: 


dtdefine NUMENTRIES 128 
HPALETTE hpal; 
PALETTEENTRY ape[NUMENTRIES]; 


plgpl = (LOGPALETTE*) LocalAlloc(LPTR, 
sizeof(LOGPALETTE) + cColors * sizeof(PALETTEENTRY)); 


plgpl->palNumEntries = cColors;. 
plgpl->palVersion = Qx30Q@; 


14 ~_—s AnsiLower 


See Also 


AnsiLower 


for (i = @, red = 0, green = 127, blue = 127; i < NUMENTRIES; 
| i++, red += 1, green += 1, blue t= 1) { 
~apeLil.peRed = | 
~ plgp1->palPalEntry[i].peRed = LOBYTE(red); 
apeLi].peGreen = 
plgpl->palPalEntry[i].peGreen = LOBYTE(green); 
apeLi].peBlue = 
plgpl->palPalEntry[i].peBlue = LOBYTE(blue); 
apeLil.peFlags = : 
plgpl->palPalEntry[Li].peFlags = PC_RESERVED; 
} 
hpal = CreatePalette(plgpl); 
LocalFree((HLOCAL) plgpl); | 
AnimatePalette(hpal, @, NUMENTRIES, (PALETTEENTRY FAR*) &ape); 


CreatePalette 


LPSTR AnsiLower(/psz) 


-LPSTR lpsz; 


Parameters 


Return Value 
Comments 


Example 


/* address of string, or specific character a 


The AnsiLower function converts a character string to lowercase. 


Ipsz 
Points to a null-terminated string or specifies a single character. If the high- 
order word of this parameter is zero, the low-order byte of the low-order word 
must contain a single character to be converted. 


The return value points to a converted character string if the function is successful. 
Otherwise, the return value is a 32-bit value that contains the converted character 
in the low-order byte of the low-order word. 


The conversion is made by the language driver for the current language (the one 
selected by the user at setup or by using Control Panel). If no language driver has 
been selected, Windows uses an internal function. 


The following example uses the AnsiLower function to convert two strings to 
lowercase for a non—case-sensitive comparison: 


/* , 
* Convert the target string to lowercase, and then 

* convert the subject string one character at a time. 
* / 


See Also 


AnsiLowerBuff 15 


AnsiLower(pszTarget); 
while (*pszTarget != '\@') { 
if (*pszTarget != (char) (DWORD) AnsiLower( 
MAKELP(@, *pszSubject) )) 
return FALSE; 
- pszTarget = AnsiNext(psztarget); 
pszSubject = AnsiNext(pszSubject); 


AnsiLowerBuff, AnsiNext, AnsiUpper 


AnsiLowerBuff 


UINT AnsiLowerBuff(/pszString, cbString) 


LPSTR I[pszString; 


UINT cbString; 


Parameters 


Return Value 


Comments 


Example 


/* address of string to convert **/ 
/* length of string **/ 


The AnsiLowerBuff function converts a character string in a buffer to lowercase. 


lpszString ; 7 
Points to a buffer containing one or more characters. 


cbString 
Specifies the number of bytes in the buffer identified by the pu pSeatTines parame- 
ter. If cbString is zero, the length is 64K (65,536). 


The return value specifies the length of the converted string if the function is 
successful. Otherwise, it 1s zero. 


The language driver makes the conversion for the current language (the one 
selected by the user at setup or by using Control Panel). If no nneuaee driver has 
been selected, Windows uses an internal function. | 


The following example uses the AnsiLowerBuff function to convert two strings 
to lowercase for a non—case-sensitive comparison: 


AnsiLowerBuff(pszSubject, (UINT) Istrlen(pszSubject)); 
AnsiLowerBuff(pszTarget, (UINT) Istrlen(pszTarget)); 
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while (*pszTarget != '\Q') { 
if (*pszTarget != *pszSubject) 
return FALSE; 
pszTarget = AnsiNext(pszTarget); 
pszSubject = AnsiNext(pszSubject); 


See Also AnsiLower, AnsiUpper 


AnsiNext [ 2.x | 
LPSTR AnsiNext(/pchCurrentChar) 
LPCSTR IpchCurrentChar; /* address of current character a | 


The AnsiNext function moves to the next character in a string. 


Parameters IpchCurrentChar 
Points to a character in a null- terminated string. 


Return Value The return value satis to the next character in the string or to the null character at 
the end of the string, if the function is successful. 


Comments The AnsiNext function can be used to move through strings where each character 
is a Single byte, or through strings where each character is two or more bytes (such 
as strings that contain characters from a Japanese character set). 


Example The following example uses the AnsiNext function to step through the characters 
| in a filename: 


/* Find the last backslash. */ 


for (lIpszFile = lpszTemp; *lpszTemp != '\Q@'; 
IpszTemp = AnsiNext(1pszTemp)) { 


if (*lpszTemp == '\\') 
lIpszFile = AnsiNext(1pszTemp) ; 


See Also AnsiPrev 


AnsiPrev 


AnsiPrev 17 


[ 2.x ] 


LPSTR AnsiPrev(/pchStart, lpchCurrentChar) 


LPCSTR I[pchStart; 


/* address of first character **/ 


LPCSTR IpchCurrentChar; /* address of current character */ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The AnsiPrev function moves to the previous character in a string. 


lpchStart 
Points to the beginning of the string. 


lpchCurrentChar 
Points to a character in a null-terminated string. 


The return value points to the previous character in the string, or to the first char- 
acter in the string if the IpchCurrentChar parameter is equal to the lpchStart 
parameter. 


The AnsiPrev function can be used to move through strings where each character 
is a single byte, or through strings where each character is two or more bytes (such 
as strings that contain characters from a Japanese character set). 


This function can be very slow, because the string must be scanned from the begin- 
ning to determine the previous character. Wherever possible, the AnsiNext func- 
tion should be used instead of this function. 


The following example uses the AnsiNext and AnsiPrev functions to change 
every occurrence of the characters ’\&’ in a string to a single newline character: 


/* Find ampersands. */ 
for (lpsz = IpszTest; *lpsz != '\@'; Ipsz = AnsiNext(Ipsz)) { 
/* Check the previous character. */ 
if (*lpsz == '&' && 
*(Ipsz2 = AnsiPrev(lpszTest, Ipsz)) == ‘\\') { 
Istrcpy(1lpsz2, 1psz); | 


*]psz2 = ONT 


} 


AnsiN ext 


18 AnsiToOem 


AnsiToO0em 


[ 2.x | 


void AnsiToOem(hpszWindows, hpszOem) 
const char _huge* hpszWindows; /* address of string to translate a 
char _huge* hpszOem; /* address of buffer for string a 


Parameters 


Return Value 


Comments 


Example 


The AnsiToOem function translates a string from the Windows character set into 
the specified OEM character set. 


hpszWindows 
Points to a null-terminated string of characters from the Windows character set. 


hpszOem 
Points to the location where the translated string is to be copied. To naneiais the 
string in place, this parameter can be the same as hpszWindows. 


This function does not return a value. 


The string to be translated can be greater than 64K in length. 


Windows-to-OEM mappings are defined by the keyboard driver, where this func- 
tion is implemented. Some keyboard drivers may have different mappings than 
others, depending on the machine environment, and some keyboard driver support 
loading different OEM character sets; for example, the standard U.S. keyboard 
driver for an IBM keyboard supports loadable code pages, with the default being 
code page 437 and the most common alternative being code page 850. (The Win- 
dows character set is sometimes referred to as code page 1007.) 


The OEM character set must always be used when accessing string data created by 
MS-DOS or MS-DOS applications. For example, a word processor should convert 
OEM characters to Windows characters when importing documents from an 
MS-DOS word processor. When an application makes an MS-DOS call, including 
a C run-time function call, filenames must be in the OEM character set, whereas © 
they must be presented to the user in Windows characters (because the Windows 
fonts use Windows characters). 


The following example is part of: a dialog box in which a user would create a 
directory by typing ¢ a name in an edit control: 


case IDOK: 
GetWindowText(GetDlgItem(hwndDlg, ID _EDITDIRNAME), szDirName, 
sizeof(szDirName) ); 
AnsiToOem(szDirName, szDirName) ; 
mkdir(szDirName) ; 
EndDialog(hwndDlg, 1); 
return TRUE; 
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See Also AnsiToOemBuff, OemToAnsi 


AnsifoOemBuff = 2 - | 


void AnsiToOemBuff(/pszWindowssStr, lpszOemStr, cbWindowsStr) 


LPCSTR IpszWindowsStr; /* address of string to translate *} 
LPSTR /pszOemsStr; /* address of buffer for translated string **/ 
/* length of string to translate oi] 


UINT cbWindowssStr; 


Parameters 


Return Value 


See Also 


AnsiUpper 


| LPSTR AnsiUpper( 
LPSTR IpszString; — 


Parameters 


The AnsiToOemBuff function translates a string from the Windows character set 
into the specified OEM character set. 


lpszWindowsStr 
Points to a buffer containing one or more characters from the Windows charac- 


ter set. 


lpszOemStr 
Points to the location where the translated string is to be copied. To translate the 


string in place, this parameter can be the same as /pszWindowssStr. 


cbWindowsStr | 
Specifies the number of bytes in the buffer identified by the InsaWindéwsSiv' pa- 


rameter. If chWindowsStr i is Zero, the length is 64K (65,536). 
This hinchon does not return a value. 


AnsiToOem, OemToAnsi 


Ips2String) 
/* address of string, or specific character og | 


The AnsiUpper function converts the given character string to uppercase. 


| ipszString a 


Points to a null- reiminated string or specifies a single character. If the high- 
order word of this parameter is zero, the low-order byte of the low- order word — 
must contain a ' single character to be converted. , 
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Return Value 
Comments 


Example 


See Also 


The return value points to a converted character string if the function parameter is 
a character string. Otherwise, the return value is a 32-bit value that contains the 
converted character in the low-order byte of the low-order word. 


The language driver makes the conversion for the current language (the one 
selected by the user at setup or by using Control Panel). If no language driver is 
selected, Windows uses an internal function. 


The following example uses the AnsiUpper function to convert two strings to up- 
percase for a non—case-sensitive comparison: 


/* 

* Convert the target string to uppercase, and then 

* convert the subject string one character at a time. 
* / 


AnsiUpper(psztarget); 
while (*pszTarget != '\@') { 
if (*pszTarget != (char) (DWORD) AnsiUpper( 
MAKELP(@, *pszSubject) )) 
return FALSE; 
pszlarget = AnsiNext(psztTarget); 
pszSubject = AnsiNext(pszSubject); 


AnsiLower, AnsiUpperBuff 


AnsiUpperBuff 


UINT AnsiUpperBuff(/pszString, cbString) 


LPSTR [pszString; 
UINT cbString; 


Parameters 


/* address of string to convert oy 
/* length of string | 


The AnsiUpperBuff function converts a character string in a buffer to uppercase. 


[pszString | 
Points to a buffer containing one or more characters. 
cbString : | 


Specifies the number of bytes in the buffer identified by the /pszString parame-_ 
ter. If cbString is zero, the length is 64K (65,536). 


Return Value 


Comments 


Example 


See Also 
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The return value weenie: the length of the converted string if the function is 
successful. 


The language driver makes the conversion for the current language (the one 
selected by the user at setup or by using Control Panel). If no language driver is 
selected, Windows uses an internal function. 


The following example uses the AnsiUpperBuff function to convert two strings to 
lowercase for a non—case- -Sensitive comparison: 


/* 

* Convert both the subject and target strings to uppercase before : 
* Comparing. 

* / 


AnsiUpperBuff(pszSubject, (UINT) Istrlen(pszSubject)); 
AnsiUpperBuff(pszTarget, (UINT) Istrlen(pszTarget)); 


while (*pszTarget != '\@') { 

if (*pszTarget != *pszSubject) 
return FALSE; 

—pszTarget = AnsiNextCoszTargat) 

rae So eee eres 


~ AnsiLower, AnsiUpper 


AnyPopup 


na 


BOOL AnyPopuptvoid) 


Parameters 


Return Value 


‘The AnyPopup function indicates whether an unowned, visible, top-level pop-up, 


or overlapped window exists on the screen. T he function searches the entire ae 


| pews screen, not just the caller’s client area. 


This function has no parameters. 


The return value is nonzero if a pop- -up window exists, even if the pop-up window 


~ is completely covered by other windows. The return value i is zero if no pop-up 


window exists. 


22 — AppendMenu 


Comments AnyPopup is a Windows 1.x function and remains for compatibility reasons. It is 
generally not useful. 


This function does not detect unowned pop-up windows or windows that do not 
. have the WS_ VISIBLE style bit set. 


See Also | GetLastActivePopup, ShowOwnedPopups 


AppendMenu 


BOOL AppendMenu(hmenu, fuFlags, idNewltem, lpNewItem) 


HMENU hmenus  _ /* handle of menu * / 
UINT fuFlags; /* menu-item flags a 
UINT idNewltem; /* menu-item identifier */ 
LPCSTR [pNewltem; /* specifies menu-item content | 


The AppendMenu function appends a new item to the end of a menu. The appli- 
cation can specify the state of the menu item by setting values in the fuFlags 
parameter. 


Parameters hmenuw 
Identifies the menu to be changed. 
fuFlags 
Specifies information about the state of the new menu item when it is added to 
the menu. This parameter consists of one or more of the values listed in the fol- 
lowing Comments section. 


idNewltem 
Specifies either the command identifier of the new menu item or, if the fuFlags 
parameter is set to MF_POPUP, the menu handle of the pop-up menu. 


lpNewltem | 
Specifies the content of the new menu item. The interpretation of the 
IpNewltem parameter depends on the value of the fuFlags parameter. 


Value Menu-item content 


MF_STRING ; Contains a long pointer to a null-terminated string. 
MF_BITMAP Contains a bitmap handle in its low-order word. 


Return Value 


Comments 


Value 


MF_OWNERDRAW 


AppendMenu 


Menu-item content 


Contains an application-supplied 32-bit value that the ap- 
plication can use to maintain additional data associated 
with the menu item. An application can find this value in 
the itemData member of the structure pointed to by the 
lParam parameter of the WM_MEASUREITEM and 
WM_DRAWITEM messages that are sent when the menu 
item is changed or initially displayed. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Whenever a menu changes (whether or not the menu is in a window that is dis- 
played), the application should call the DrawMenuBar function. 


Each of the following groups lists flags that are yas exclusive and cannot be 


used together: 


~™ MF_DISABLED, MF_ ENABLED, and MF_GRAYED 


= MF_BITMAP, MF_STRING, and MF_OWNERDRAW 


™ MF_MENUBARBREAK and MF_MENUBREAK 


= MF_CHECKED and MF_UNCHECKED 


Following are the flags that can be set in the fuFlags parameter: 


Value 


MF_BITMAP 


MF_CHECKED 


MF_DISABLED 


MF_ENABLED 


-MF_GRAYED 


MF_MENUBARBREAK 


MF MENUBREAK 


Meaning 


Uses a bitmap as the item. The low-order word of the | 
lpNewltem parameter contains the handle of the bitmap. 


Places a check mark next to the item. If the application 
has supplied check mark bitmaps (see the SetMenultem- 
Bitmaps function), setting this flag displays the “check 
mark on” bitmap next to the menu item. 


Disables the menu item so that it cannot be selected, but 
does not gray it. 


Enables the menu item so that it can be selected, and re- | 
~ stores it from its grayed state. : 


Disables the menu item so that it cannot be selected, and 
grays it. , 
Same as MF _MENUBREAK except that, for pop-up 

_menus, separates the new column from the old column 
with a vertical line... | 
Places the item on a new line for static menu-bar items. 
For pop-up menus, places the item in a new column, 
with no dividing line between the columns. 
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Example 


See Also 


Value Meaning 


MF_OWNERDRAW Specifies that the item 1s an owner-drawn item. The win- 
dow that owns the menu receives a 
WM_MEASUREITEM message when the menu is dis- 
played for the first time to retrieve the height and width 
of the menu item. The WM_DRAWITEM message is 
then sent whenever the owner window must update the 
visual appearance of the menu item. This option is not 
valid for a top-level menu item. 


MF_POPUP | Specifies that the menu item has a pop-up menu as- 

| sociated with it. The idNewltem parameter specifies a 
handle to a pop-up menu to be associated with the item. 
This is used for adding either a top-level pop-up menu or 
adding a hierarchical pop-up menu to a pop-up menu 
item. | 

MF_SEPARATOR Draws a horizontal dividing line. Can be used only in a 

3 pop-up menu. This line cannot be grayed, disabled, or 

highlighted. The JpNewItem and idNewlItem parameters 
are ignored. 


MF_STRING | Specifies that the menu item is a character string; the 
| IpNewltem parameter points to the string for the menu 
item. _ | 
MF_UNCHECKED Does not place a check mark next to the item (default). If 


the application has supplied check mark bitmaps (see 
SetMenultemBitmaps), setting this flag displays the 
“check mark off’ bitmap next to the menu item. 


The following example uses the AppendMenu function to append three items to a 
floating pop-up menu: 


POINT ptCurrent; 
HMENU hmenu; 


ptCurrent = MAKEPOINT(1Param) ; 


_hmenu = CreatePopupMenu(); 


AppendMenu(hmenu, MF_ENABLED, IDM_ELLIPSE, “Ellipse™); 
AppendMenu(hmenu, MF_ENABLED, IDM_SQUARE, "“Square™); 


“AppendMenu(hmenu, MF_ENABLED, IDM_TRIANGLE, "Triangle"™); 


ClientToScreen(hwnd, &ptCurrent); 
TrackPopupMenu(hmenu, TPM_LEFTALIGN, ptCurrent.x, 
ptCurrent.y, @, hwnd, NULL); 


CreateMenu, DeleteMenu, DrawMenuBar, InsertMenu, RemoveMenu, Set- 
MenultemBitmaps | 


Arc 


Arc | | 2.x | 


BOOL Arc(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXStartArc, nYStartArc, nXEndArc, 


nYEndArc) 
HDC hdc; /* handle of device context */ 
int nLeftRect; _ /* x-coordinate upper-left corner bounding rectangle - */ 
int nJopRect; /* y-coordinate upper-left corner bounding rectangle sa 
int nRightRect; _ /* x-coordinate lower-right corner bounding rectangle */ 
int nBottomRect; /* y-coordinate lower-right corner bounding rectangle sa 
int nXStartArc; _ —_‘/* x-coordinate arc starting point */ 
int nYStartArc; /* y-coordinate arc starting point */ 
int nXEndArc; /* x-coordinate arc ending point se 
— Int nYEndArc; /* y-coordinate arc ending point */ 
The Arc function draws an elliptical arc. | 
Parameters hdc 
- Identifies the device context. 
nLeftRect : 
Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle. . 
nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the bounding 
rectangle. 
nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the dounding 
~ rectangle. 
nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the bounding 
rectangle. | 
nX StartArc 


Specifies the logical x-coordinate of the point that defines the arc’s paras 
point. This point need not lie exactly on the arc. — oo 


| nYStartArc 
‘Specifies the logical y- -coordinate of the point that defines the « arc’s starting | 
- point. This point need not lie exactly on the arc. | | 


nXEndArc | | ae 
Specifies the logical x-coordinate of the point that séfines the arc’ s Srdponie 
This point need not lie exactly on the arc. 7 , 


nYEndArc | 
Specifies the logical s-courdilatz of the point that défines the arc’s endpoint. 
This point need not lie exactly on the arc. 
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Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments | The arc drawn by using the Arc function is a segment of the ellipse defined by the 
specified bounding rectangle. The starting point of the arc is the point at which a 
ray drawn from the center of the bounding rectangle through the specified starting 
point intersects the ellipse. The end point of the arc is the point at which a ray 
drawn from the center of the bounding rectangle through the specified end point in- 
tersects the ellipse. The arc is drawn in a counterclockwise direction. Since an arc 
is not a closed figure, it is not filled. 


Both the width and the height of a rectangle must be greater than 2 units and less 
than 32,767 units. | 


Example The following example uses a RECT structure to store the points defining the 
bounding rectangle and uses POINT structures to store the coordinates that 
specify the beginning and end of the arc: 


HDC hdc; 

RECT rc = { 10, 10, 180, 140 }; 
POINT ptStart = { 12, 12 }; 
POINT ptEnd = { 128, 135 }; 


Arc(hde, rc.left, re.top, rc.right, rc.bottom, 
ptStart.x, ptStart.y, ptEnd.x, ptEnd.y); 


See Also ~ Chord 


ArrangelconicWindows a 


UINT ArrangelIconicWindows(hwnd) 
HWND hwnd; /* handle of parent window a | 


The ArrangelIconicWindows function arranges all the minimized (iconic) child 
windows of a parent window. 


Parameters. hwnd 
Identifies the parent window. 


Return Value The return value is the height of one row of icons if the function is successful. 
Otherwise, it is zero. | 


Comments 


See Also 


BeginDeferWindowPos 27 


An application that maintains its own minimized child windows can call Arrange- 
Iconic Windows to arrange icons in a client window. This function also arranges 
icons on the desktop window, which covers the entire screen. The GetDesktop- 
Window function retrieves the window handle of the desktop window. 


An application sends the WM_MDITCONARRANGE message to the MDI client 
window to prompt the client window to arrange its minimized MDI child windows. 


GetDesktopWindow 


BeginDeferWindowPos 9 ' 


HDWP BeginDefer WindowPos(cWindows) 


int cWindows; | 


Parameters — 


Return Value 


Comments 


See Also 


/* number of windows | 


The BeginDefer WindowPos function returns a handle of an internal structure. 
The Defer WindowPos function fills this structure with information about the tar- 
get position for a window that is about to be moved. The EndDefer WindowPos 
function accepts a handle of this structure and instantaneously repositions the win- 
dows by using the information stored in the structure. 


cWindows | 
Specifies the initial number of windows for which to store position information 
in the structure. The DeferWindowPos function increases the size of the struc- 
ture if necessary. 


The return value identifies the internal structure if the function is successful. Other- 
wise, it is NULL. | 


If Windows must increase the size of the internal structure beyond the initial size 
specified by the cWindows parameter but cannot allocate enough memory to do so, 
Windows fails the entire begin/defer/end window-positioning sequence. By speci- 
fying the maximum size needed, an application can detect and handle failure early 
in the process. | | 


Defer WindowPos, EndDeferWindowPos 
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BeginPaint , ca OS ax] 


- HDC BeginPaint(hwnd, Ipps) = 
HWND hwnd; /* handle of window to paint | 
PAINTSTRUCT FAR*® Ipps; /* address of structure with paint information st | 


The BeginPaint function prepares the specified window for painting and fills a 
PAINTSTRUCT structure with information about the painting. 


Parameters hwnd 
Identifies the window to be repainted. 


[pps 
— Points to the PAINTSTRUCT structure that will receive the painting informa- _ 
tion. The PAINTSTRUCT structure has the following form: | 


typedef struct tagPAINTSTRUCT { /* ps */ 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


For a full sescopaen of this structure, see the M ose Windows Program- 
mer’s ROCTERCE: Volume 3. 


Return Value The return value is the handle of the device context for the given window if the 
function is successful. | 


Comments The BeginPaint function automatically sets the clipping region of the device con- 
text to exclude any area outside the update region. The update region 1s set by the 
InvalidateRect or InvalidateRgn function and by the system after sizing, 
moving, creating, scrolling, or any other operation that affects the client 
area. If the update region is marked for erasing, BeginPaint sends a 
WM_ERASEBKGND message to the window. 


An application should not call BeginPaint except in response to a WM_PAINT 
message. Each call to the BeginPaint function must have a corresponding call to 
the EndPaint function. | 


If the caret is in the area to be painted, BeginPaint automatically hides the caret to 
prevent it from being erased. , 


If the window’s class has a background brush, BeginPaint will use that brush to = 
erase the background of the update region before returning. 


Example 


See Also 


BitBIt 


BitBit 29 


The following example calls an application-defined function to paint a bar graph 
in a window’s client area during the WM_PAINT message: 


PAINTSTRUCT ps; 


case WM PAINT: 
BeginPaint(hwnd, &ps); 


EndPaint(hwnd, &ps); 
break; 


EndPaint, InvalidateRect, InvalidateRgn, ValidateRect, ValidateRgn 


BOOL BitBlt(hdcDest, nXDest, nYDest, nWidth, nHeight, hdcSrc, nXSrc, nYSrc, dwRop) 
*/ 


HDC hdcDest; 
int nXDest; 

int nYDest; 

int nWidth; 

int nHeight; 
HDC hdcSrc; 

int nXSrc3 

int nYSrc3 
DWORD dwRop; 


Parameters 


/* handle of destination device context 


/* upper-left corner destination rectangle */ 
/* upper-left corner destination rectangle a | 
* bitmap width | | **/ 
/* bitmap height | =) 
/* handle of source device context **/ 
/* upper-left corner source bitmap *) 
/* upper-left corner source bitmap */ 
/* raster operation for copy ‘| 


The BitBlt function copies a bitmap from a specified device context to a destina- 
tion device context. 


hdcDest 
Identifies the deceiation device context. 
nXDest 


Specifies the logical x- “coordinate of the upper-left comer of the destination 
_ rectangle. 


nYDest 
Specifies the logical y- soporlinate of the upper-left corner of the destination 
rectangle. 


nWidth 
Specifies the width, in logical units, of the destination rectangle and source bit- 
map. : 
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nHe ight 
Specifies the hieiehits in lo sai units, of the destination rectangle and source bit- 
map. 


hdcSre 
Identifies the device context from which the bitmap will be copied. This 
parameter must be NULL if the dwRop parameter specifies a raster operation 
that does not include a source. This parameter can specify a memory device 
context. 


nXSrc 
Specifies the logical x-coordinate of the ippersicfi corner of the source bitmap. 


nYSrc 
Specifies the logical y-coordinate of the upper- Jeft comer of the source bitmap. 


dwRop 
Specifies the raster operation to be performed. Raster operation codes define 
how the graphics device interface (GDI) combines colors in output operations 
that involve a current brush, a possible source bitmap, and a destination bitmap. 
This parameter can be one of the following: 


Code Description 
BLACKNESS Turns all output black. 
DSTINVERT Inverts the destination bitmap. 7 
MERGECOPY ~~ Combines the pattern and the source bitmap by using the 
: Boolean AND operator. | 
MERGEPAINT Combines the inverted source bitmap with the destination bit- 


map by using the Boolean OR operator. 
NOTSRCCOPY Copies the inverted source bitmap to the destination. 


NOTSRCERASE Inverts the result of combining the destination and source bit- 
maps by using the Boolean OR operator. 


PATCOPY Copies the pattern to the destination bitmap. 

PATINVERT Combines the destination bitmap with the pattern by using the 
Boolean XOR operator. | 

PATPAINT Combines the inverted source bitmap with the pattern by _ 


using the Boolean OR operator. Combines the result of this 
operation with the destination bitmap by using the Boolean 


| : OR operator. 
SRCAND | Combines pixels of the destination and source bitmaps by 
S _ using the Boolean AND operator. © 
SRCCOPY Copies the source bitmap to the destination bitmap. | 
SRCERASE — Inverts the destination bitmap and combines the result with _ 
the source bitmap by using the Boolean AND operator. 
_ SRCINVERT Combines pixels of the destination and source bitmaps by 


using the Boolean XOR operator. 


Return Value 


Comments 


Example 
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Code Description 
~ SRCPAINT Combines pixels of the destination and source bitmaps by 
using the Boolean OR operator. 
WHITENESS Turns all output white. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


An application that uses the BitBIt function to copy pixels from one window to 


another window or from a source rectangle in a window into a target rectangle in 


the same window should set the CS_BYTEALIGNWINDOW or 
CS_BYTEALIGNCLIENT flag when registering the window classes. By aligning 


the windows or client areas on byte boundaries, the application can ensure that the 


BitBlt operations occur on byte-aligned rectangles. BitBIt operations on byte- 
aligned rectangles are considerably faster than BitBIt operations on rectangles that 
are not byte-aligned. , 


GDI transforms the nWidth and nHeight parameters, once by using the destination 
device context, and once by using the source device context. If the resulting ex- 
tents do not match, GDI uses the StretchBlt function to compress or stretch the 
source bitmap as necessary. If destination, source, and pattern bitmaps do not have 
the same color format, the BitBIt function converts the source and pattern bitmaps 
to match the destination. The foreground and background colors of the destination 
bitmap are used in the conversion. | 


When the BitBlt function converts a monochrome bitmap to color, it sets white 
bits (1) to the background color and black bits (0) to the foreground color. The 
foreground and background colors of the destination device context are used. To 
convert color to monochrome, BitBIt sets pixels that match the background color 
to white and sets all other pixels to black. BitBIt uses the foreground and back- 
ground colors of the source (color) device context to convert from color to mono- 
chrome. 


The foreground color is the current text color for the specified device context, and 
the background color is the current background color for the specified device con- 
text. 


Not all devices support the BitBlt function. An application can determine whether 
a device supports BitBlt by calling the eee function and nye 
the RASTERCAPS index. 


For a complete list of the fasteroperation codes, see the M icrosoft Wiktoiis Pro- 
grammer ’s Reference, Volume 4. ; 


The following ecaiiple loads a bitmap, retrieves its dimensions, and displays it in 
a window: : 


32 BringWindowToTop 


See Also 


HDC hdc, hdcMemory; 
HBITMAP hbmpMyBitmap, hbmp01d; 
BITMAP bm; 


hbmpMyBitmap = LoadBitmap(hinst, “MyBitmap"); 
GetObject(hbmpMyBitmap, sizeof(BITMAP), &bm); 


hdc = GetDC(hwnd); 
hdcMemory = CreateCompatibleDC(hdc); 
hbmpOld = SelectObject(hdcMemory, hbmpMyBitmap) ; 


BitBlt(hdc, 0, @, bm. bmWidth, bm.bmHeight, hdcMemory, 0, Q, SRCCOPY); 


SelectObject(hdcMemory, hbmp0Old); 


| neveesvechdcnanorye: 


ReleaseDC(hwnd, hdc); 


GetDeviceCaps, PatBit, SetTextColor, StretchBIt, StretchDIBits 


-BringWindowToTop [2x | 


BOOL Bring Window ToTop(iwnd) 


HWND hwnd; 


Parameters 


Return Value 


Comments _ 


See Also 


/* handle of window —*/ 


The Bring WindowToTop function brings the given pop-up or child window 
(including an MDI child window) to the top of a stack of overlapping windows. 
In addition, it activates pop-up, top-level, and MDI child windows. The Bring- 
WindowToTop function should be used to uncover any window that is partially 
or completely obscured by any overlapping windows. 


hwnd 
Identifies the pop-up or child window to s bitte to the top. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Calling this function is similar to calling the Set WindowPos function to change a 


window’s position in the Z-order. The BringWindowToTop function does not 
make a window a top- -level window. 


SetWindowPos 


BuildCommDGB 


int BuildCommDCB(/pszDef, [pdcb) 


LPCSTR /pszDef; 
DCB FAR* Ipdcb; 


Parameters 


/* address of device-control string 
/* address of device-control block 


lpszDef 


BuildCommDCB 


| 
ay | 
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[ 2.x | 


The BuildCommDCB function translates a device-definition string into appro- 
priate serial device control block (DCB) codes. 


Points to a null-terminated string that specifies device-control information. The 
string must have the same form as the parameters used in the MS-DOS mode 


command. 


lpdcb 


Points to a DCB structure that will receive the translated string. The structure 
defines the control settings for the serial-communications device. The DCB 


structure has the following form: 


typedef struct tagDCB 
t 


BYTE 
UINT 
BYTE 
BYTE 
BYTE 
UINT 
UINT 
UINT 


Id; 
BaudRate; 
ByteSize; 
Parity; 
StopBits; 
RisTimeout; 
CtsTimeout; 
DsrTimeout; 


UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 


fBinary 
fRtsDisable 
fParity | 
fOutxCtsFlow 
fOutxDsrFlow 
f Dummy 
fDtrDisable 


we we 


we 


ee ee ee ee ee ee Pr 
OE DO ee 


we we we we 


UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 


fOutx 
fInx 
fPeChar 
fNull 
fChEvt 
fDtrf low 
fRtsflow 
fDummy2 


ee ee ee ee ee. ee ees ee 
mS he me pe Re pe pe 


we we we we we we we we 


/* 


/* 
/* 


/* 


/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 


—[k 


/* 
/* 
/* 


dcb 


internal device identifier 
baud rate 

number of bits/byte, 4-8 
@-4=none,odd,even,mark, space 
@,1,2 = 1,-1.5, 2 

timeout for RLSD to be set 
timeout for CTS to be set 
timeout for DSR to be set 


binary mode (skip EOF check) 
don't assert RTS at init time 
enable parity checking 

CTS handshaking on output 

DSR handshaking on output 
reserved . 

don't assert DIR at init time 


enable 
enable 
enable 


output XON/XOFF 

input XON/XOFF 

parity err replacement 
enable null stripping 

enable Rx character event 

DTR handshake on input 

RTS handshake on input 


* / 


* / 
*/ 
* / 
* / 
* / 
* / 
at / 
* / 


* / 
* / 
* / 
* / 
* / 
* / 
* / 


* / 
* / 
* / 
* / 
** / 
** / 
* / 
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Return Value 


Comments 


Example 


char XonChar; /* Tx and Rx XON character | 
char XoffChar;. /* Tx and Rx XOFF character ok 
UINT XonLim; /* transmit XON threshold * / 
UINT XoffLim; /* transmit XOFF threshold © gh 
char PeChar; 7 _/* parity error replacement char */ 
char EofChar; /* end of Input character x / 
char EvtChar; : /* received event character 2 / 
UINT TxDelay; /* amount of time between chars * / 
} DCB; — 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


The return value is zero if the function is successful. Otherwise, it is —1. 


The BuildCommDCB function only fills the buffer. To apply the settings to a 
port, an application should use the SetCommState function. 


By default, BuildCommDCB specifies XON/XOFF and hardware flow control as 
disabled. To enable flow control, an application should set the appropriate mem- 
bers in the DCB structure. | | 


The following example uses the BuildCommDCB and SetCommState functions 
to set up COM1 to operate at 9600 baud, with no parity, 8 data bits, and 1 stop bit: 


idComDev = OpenComm("COM1", 1024, 128); 

if (idComDev < 0) { . 
ShowError(idComDev, "OpenComm") ; 
return Q; 

} 


err = BuildCommDCB("COM1:9600,n,8,1", &dcb); 


if cerr < @) { 


See Also 


ShowError(err, "BuildCommDCB") ; 
return Q; 
} 


err = SetCommState(&dcb) ; 

if (err < @) { 
ShowError(err, "SetCommState"); 
return @; 


Vis 


SetCommState 
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CallMsgFilter_ oa 


BOOL CallMsgFilter(/pmsg, nCode) 


MSG FAR* Ipmsg; 


int nCode; 


Parameters 


Return Value | 


Comments 


See Also 


/* address of structure with message data | 
/* processing code | =) 


The CallMsgFilter function passes the given message and code to the current mes- 
sage-filter function. The message-filter function is an application-specified func- 
tion that examines and modifies all messages. An application specifies the 

function by using the SetWindowsHook function. 


— Ipmsg 


Points to an MSG structure that contains the meee to 5 be filtered. The MSG 
structure has the following form: 


typedef struct tagMSG {. /* msg */ 
HWND hwnd; . | 
UINT message; 
_ WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT. ‘pt; 
. MSG: | | 


- Fora full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume3. 


; nCode 


Specifies a code used by the filter function to determine hoy to process the mes- 
Sage. | 


The return value specifies the state of message processing. It is zero if the message © 
Should be processed or nonzero if the message should not be processed further. 


The CallMsgFilter function is usually called by Windows to let applications ex- 
amine and control the flow of messages during internal processing in menus io : 
scroll bars or when moving or sizing a window. : 


Values given for the nCode parameter must not conflict with any of the MSGF_ 


and HC_ values passed by Windows to the message-filter function. 


| Set WindowsHook 
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CallNextHookEx ra] 


LRESULT CallNextHookEx(hHook, nCode, wParam, lParam) 


HHOOK hHook; /* handle of hook function | */ 
int nCode; /* hook code */ 
WPARAM wParam; /* first message parameter */ 
~ LPARAM /Param; /* second message parameter +) 


The CallNextHookEx function passes the hook information to the next hook func- 
tion in the hook chain. 


Parameters hHook | 
Identifies the current hook function. 


nCode 
Specifies the hook code to pass to the next hook function. A hook function uses 


this code to determine how to process the message sent to the hook. 


wParam 
Specifies 16 bits of additional message-dependent information. 


[Param 
Specifies 32 bits of additional message-dependent information. 


Return Value _ The return value specifies the result of the message processing and depends on the 
value of the nCode parameter. 


Comments Calling the CallNextHookEx function is optional. An application can call this 
function either before or after completing any processing in its own hook function. 
If an application does not call CallNextHookEx, Windows will not call the hook 
functions that were installed before the application’s hook function was installed. 


See Also Set WindowsHookEx, Unhook WindowsHookEx 


CallWindowProc Pax] 


LRESULT CallWindowProc(wndprcPrev, hwnd, uMsg, wParam, lParam) | 


WNDPROC wiadprcPrev; /* instance address of previous procedure | 
HWND hwnd; /* handle of window | it | 
UINT uMsg; /* message | | =) 
WPARAM wParam; /* first message parameter ) 


LPARAM /Param; /* second message parameter st 


Parameters 


Return Value 


Comments 


See Also 


CallWndProc 
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The CallWindowProc function passes message information to the specified win- 
dow procedure. 


wndprcPrev 
Specifies the procedure-instance ees of the previous window procedure. 


Phwiid 


Identifies the window that will receive the message. 


uMsg 
Specifies the message. 


wParam 
Specifies 16 bits of additional message- -dependent information. 


[Param | 
Specifies 32 bits of additional message- ip teen information. 


The return value specifies the result of the message processing and depends on the 


message sent. 


The CallWindowProc function is used for window subclassing. Normally, all 
windows with the same class share the same window procedure. A subclass is a 
window or set of windows belonging to the same window class whose messages 
are intercepted and processed by another window procedure (or procedures). | 
before being passed to the window procedure of that class. 


~The Set WindowLong function creates the subclass by changing the window pro- 


cedure associated with a particular window, causing Windows to call the new win- 
dow procedure instead of the previous one. Any messages not processed by the 
new window procedure must be passed to the previous window procedure by _ 
calling CallWindowProc. This allows you to create a chain of window proce- | 
dures. 


SetWindowLong 


LRESULT CALLBACK CallWndProc(code, wParam, aren) 


int code; 


WPARAM wParam; 
| LPARAM lParam; 


/* process-message flag tf 
/* current-task flag **/ 
/* address of structure with message data */ 


The CallWndProc function is a library- defined callback function that the system © 
calls whenever the SendMessage function is called. The system passes the : 
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Parameters 


Return Value 


Comments 


See Also 


message to the callback function before passing the message to the destination win- 
dow procedure. 


code 
Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If the code parameter is less than zero, the callback 
function should pass the message to CallNextHookEx without further process- 
ing. 

wParam 
Specifies whether the message is sent by the current task. This parameter is non- 
zero if the message is sent; otherwise, it is NULL. 


lParam — | 
Points to a structure that contains details about the message. The following 
shows the order, type, and description of each member of the structure: 


Member __s Description 

lParam Contains the /Param parameter of the message. 
wParam Contains the wParam parameter of the message. 
uMsg Specifies the message. 

hWnd Identifies the window that will receive the message. 


The callback function should return zero. 


The CallWndProc callback function can examine or modify the message as neces- 
sary. Once the function returns control to the system, the message, with any modi- 
fications, is passed on to the window procedure. 


This callback function must be in a dynamic-link library. 


_ An application must install the callback function by specifying the 


WH_CALLWNDPROC filter type and the procedure-instance address of the call- 
back function in a call to the Set WindowsHookEx function. 


CallWndProc is a placeholder for the library- defined function name. The actual 


name must be exported by meee it in an EXPORTS statement in the library’s 
module- definition file. 


CallNextHookEx, SendMessage, SetWindowsHookEx 
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Catch Pex] 


int Catch(/pCatchBuf) 
int FAR* [pCatchBuf; /* address of buffer for array tf 


The Catch function captures the current execution environment and copies it to a 
buffer. The Throw function can use this buffer later to restore the execution en- 
vironment. The execution environment includes the state of all system registers 
and the instruction counter. 


Parameters [pCatchBuf 
, _ Points to a memory buffer large enough to contain a CATCHBUF array. 


Return Value The Catch function returns immediately with a return value of zero. When the 
_ Throw function is called, it returns again, this time with the return value specified 
in the nErrorReturn parameter of the Throw function. 


Comments The Catch function is similar to the C run-time function setjmp. 


Example The following example calls the Catch function to save the current execution 
environment before calling a recursive sort function. The first return value 
from Catch is zero. If the doSort function calls the Throw function, execution 
will again return to the Catch function. This time, Catch will return the 
STACKOVERFLOW error passed by the doSort function. The doSort function is 
recursive—that is, it calls itself. It maintains a variable, wStackCheck, that is used 
to check to see how much stack space has been used. If more then 3K of the stack 
has been used, doSort calls Throw to drop out of all the nested function calls back 
into the function that called Catch. 


define STACKOVERFLOW 1 


UINT uStackCheck; 
CATCHBUF catchbuf; 


{ 
int iReturn; 
char szBuf[80];— 
if ((iReturn = Catch((int FAR) catchbuf)) != @) { 


: IP Error Pe goes here. */ 
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else { 
uStackCheck = Q@; /* initializes stack-usage count */ 
doSort(1, 100); /* calls sorting function * / 
} 
break; 
} 
void doSort(int sLeft, int sRight) 
{ 
int sLast; 
/* ; 
* Determine whether more than 3K of the stack has been 
—%* used, and if so, call Throw to drop back into the 
* Original calling application. 
* 
* The stack is incremented by the size of the two parameters, 
* the two local variables, and the return value (2 for a near 
* function call). 
* / 
uStackCheck += (sizeof(int) * 4) + 2; 
if (uStackCheck > (3 * 1024)) 
Throw( (int FAR*) catchbuf, STACKOVERFLOW) ; 
. /* A sorting algorithm goes here. */ 
doSort(sLeft, sLast - 1); /* note recursive call * / 
uStackCheck -= 18; /* updates stack-check variable */ 
} . 
See Also Throw 


CBTProc | - ter 


LRESULT CALLBACK CBTProc(code, wParam, lParam) 


int code; /* CBT hook code */ 
WPARAM wParam; /* depends on the code parameter */ 
LPARAM /Param; /* depends on the code parameter ba 


The CBTProc function is a library-defined callback function that the system calls 
before activating, creating, destroying, minimizing, maximizing, moving, or sizing 
a window; before completing a system command; before removing a mouse or 


Parameters 
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keyboard event from the system message queue; before setting the input focus; or 
before synchronizing with the system message queue. 


The value returned by the callback function determines whether to allow or pre- 


vent one of these operations. 


code 


Specifies a computer-based-training (CBT) hook code that identifies the opera- 
tion about to be carried out, or a value less than zero if the callback function 
should pass the code, wParam, and lParam parameters to the CallNextHookEx 
function. The code parameter can be one of the following: 


Code 
HCBT_ACTIVATE 


HCBT_CLICKSKIPPED 


HCBT_CREATEWND 


HCBT_DESTROYWND 


- HCBT_KEYSKIPPED 


-HCBT_MINMAX 


Meaning 


Indicates that the system is about to activate a win- 
dow. 


Indicates that the system has removed a mouse mes- 


sage from the system message queue. A CBT applica- 


tion that must install a journaling playback filter in 
response to the mouse message should do so when it 
receives this hook code... 


Indicates that a window is about to be created. T Be 
system calls the callback function before sending the 
WM_CREATE or WM_NCCREATE message to the 
window. If the callback function returns TRUE, the 


system destroys the window—the CreateWindow 


function returns NULL, but the WM_DESTROY mes- 
Sage is not sent to the window. If the callback func- 
tion returns FALSE, the window is created normally. 


At the time of the HCBT_CREATEWND notifica- 


tion, the window has been created, but its final size 


and position may not have been determined, nor has 
its parent window been established. 
It is possible to send messages to the newly created 


window, although the window has not yet received 
WM_NCCREATE or WM_CREATE messages. 


It is possible to change the Z-order of the newly — 
created window by modifying the hwndInsertAfter 
member of the CBT_CREATEWND structure. 
Indicates that a window is about to be destroyed. 
Indicates that the system has removed a keyboard 
message from the system message queue. A CBT ap- 


plication that must install a journaling playback filter 


in response to the keyboard message should do so 


when it receives this hook code. 


Indicates that a window is about to be minimized or 
maximized. | 
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Return Value 


Comments 


Code _ Meaning 

HCBT_MOVESIZE Indicates that a window is about to be moved or sized. 

HCBT_QS Indicates that the system has retrieved a 
WM_QUEUESYNC message from the system mes- 
Sage queue. , 

HCBT_SETFOCUS Indicates that a window is about to receive the input 
focus. 


HCBT_SYSCOMMAND Indicates that a system command is about to be car- 
ried out. This allows a CBT application to prevent 
task switching by hot Keys. 


wParam 
This parameter depends on the code parameter. See the following Comments 
section for details. 


lParam 


This parameter depends on the code parameter. See the following Comments 
section for details. 


For operations corresponding to the following CBT hook codes, the callback func- 


tion should return zero to allow the operation, or 1 to prevent it: 


HCBT_ACTIVATE 
HCBT_CREATEWND 
HCBT_DESTROYWND 
HCBT_MINMAX 
HCBT_MOVESIZE 
HCBT_SYSCOMMAND 


The return value is ignored for operations corresponding to the following CBT 
hook codes: — | 


HCBT_CLICKSKIPPED 
HCBT_KEYSKIPPED 
HCBT_QS 


The callback function should not install a playback hook except in the situations 
described in the preceding list of hook codes. 


This callback function must be in a dynamic-link library. 


An application must install the callback function by specifying the WH_CBT filter 
type and the procedure-instance address of the callback function in a call to the 
SetWindowsHookEx function. 


CBTProc 


CBTProc is a placeholder for the library-defined function name. The actual name 
must be exported by including it in an EXPORTS statement in the library’s 
module-definition file. 


The following table describes the wParam and [Param a for each 
HCBT_ constant. 


Constant 
HCBT_ACTIVATE 


HCBT_CLICKSKIPPED 


HCBT_CREATEWND 


HCBT_DESTROYWND 


HCBT_KEYSKIPPED 
HCBT_MINMAX 


HCBT_MOVESIZE 
HCBT_QS 


HCBT_SETFOCUS 


wParam 


Specifies the handle of the win- 
dow about to be activated. 


Identifies the mouse message re- 
moved from the system mes- 
Sage queue. 


Specifies the handle of the new 
window. 


Specifies the handle of the win- 


dow about to be destroyed. 


Identifies the virtual key code. 


Specifies the handle of the win- 
dow being minimized or maxi- 
mized. 


Specifies the handle of the win- 
dow to be moved or sized. 

This parameter is undefined; it 
should be set to 0. 

Specifies the handle of the win- 
dow gaining the input focus. 


[Param 


Specifies a long pointer to a CBT- 
ACTIVATESTRUCT structure that con- 
tains the handle of the currently active 
window and specifies whether the activation 
is changing because of a mouse click. 


Specifies a long pointer to a MOUSE- 


~ HOOKSTRUCT structure that contains the 


hit-test code and the handle of the window 
for which the mouse message is intended. 
For a list of hit-test codes, see the descrip- 
tion of the WM_NCHITTEST message. 
Specifies a long pointer to a 
CBT_CREATEWND data structure that 
contains initialization parameters for the win- 
dow. 

This parameter is undefined and should be 
set to OL. | 


_ Specifies the repeat count, scan code, key- 


transition code, previous key state, and con- | 
text code. For more information, see the 
description of the WM_KEYUP or 
WM_KEYDOWN message. 


The low-order word specifies a show- 
window value (SW_) that specifies the 
operation. For a list of show-window values, 
see the description of the ShowWindow 
function. The high-order word is undefined. 
Specifies a long pointer to a RECT structure 
that contains the coordinates of the window. 
This parameter is undefined and should be 
set to OL. 

The low-order word specifies the handle of 


the window losing the input focus. The high- 
order word is undefined. 
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Constant | - wParam lParam 
HCBT_SYSCOMMAND Specifies a system-command If wParam is SC_HOTKEY, the low-order 
value (SC_) that specifies the word of [Param contains the handle of the 
system command. Formore = —_~window that task switching will bring to the 
- information about system foreground. If wParam is not SC_HOTKEY 
command values, see the and a System-menu command is chosen 
description of the with the mouse, the low-order word of 
WM_SYSCOMMAND lParam contains the x-coordinate of the cur- 
message. — | sor and the high-order word contains the 


y-coordinate. If neither of these conditions is 
true, [Param is undefined. 


See Also CallNextHookEx, SetWindowsHookEx 


ChangeClipboardChain [2x] 


BOOL ChangeClipboardChain(hwnd, hwndNext) 
HWND hwnd; | /* handle of window to remove =), 
HWND hwndNexts /* handle of next window */ 


The ChangeClipboardChain function removes the window identified by the 
hwnd parameter from the chain of clipboard viewers and makes the window iden- 
tified by the hwndNext parameter the descendant of the hwnd parameter’s ancestor 
in the chain. 


Parameters hwnd 
| Identifies the window that is to be removed from the chain. The handle must 
have been passed to the SetClipboard Viewer function. 


hwndNext — | 
Identifies the window that follows hwnd in the clipboard-viewer chain (this is 
the handle returned by the SetClipboard Viewer function, unless the sequence 
was changed in response to a WNECH ANGEL BCH IN message). 


Return Value The return ee is nonzero if the function is successful. Otherwise, it is zero. 


See Also | SetClipboard Viewer 


CheckDigButton 45 


ChangeMenu Pax] 


The Microsoft Windows 3.1 Software Development Kit (SDK) has replaced this 
function with five specialized functions, listed as follows: | 


Function Description 

AppendMenu Appends a menu item to the end of a menu. 

DeleteMenu Deletes a menu item from a menu, destroying the menu item. 

InsertMenu Inserts a menu item into a menu. 

ModifyMenu Modifies a menu item in a menu. 

RemoveMenu Removes a menu item from a menu but does not destroy the menu 
item. 


Applications written for Windows versions earlier than 3.0 may continue to call 
ChangeMenu as previously documented. Applications written for Windows 3.0 
and 3.1 should call the new functions. 


Example The following example shows a call to ChangeMenu and how it would be rewrit- 
ten to call AppendMenu: 
ChangeMenu(hMenu, /* handle of menu * / 
0, _ /* position parameter not used */ 
"&White”, _— /* menu-item string | * / 
IDM_PATTERNI, /* menu-item identifier * / 
MF_APPEND | MF_STRING | MF_CHECKED); /* flags of 
AppendMenu(hMenu, | /* handle of menu x] 
MF_STRING | MF_CHECKED, /* flags * / 
IDM_PATTERNI, . /* menu-item identifier */ 
"aWhite™); /* menu-item string * / 
See Also AppendMenu, DeleteMenu, InsertMenu, ModifyMenu, RemoveMenu — 


CheckDigButton aes ax] 


void CheckDigButton(hwndDlg, idButton, uCheck) 
HWND hwndDig; /* handle of dialog box mh 
int idButton; /* button-control identifier */ 
UINT uCheck; /* check state | i! ae 
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Parameters 


Return Value 


Comments 


See Also 


CheckMenultem 


The CheckDlgButton function selects (places a check mark next to) or clears (re- 
moves a check mark from) a button control, or it changes the state of a three-state 
button. | 


hwndDlg 
Identifies the dialog box that contains the button. 


idButton | | 
Identifies the button to be modified. 


uCheck 
Specifies the check state of the button. If this parameter is nonzero, 
CheckDIgButton selects the button; if the parameter is zero, the function clears 
the button. For a three-state check box, if uCheck is 2, the button is grayed; if 
uCheck is 1, itis selected; if uCheck is O, it is cleared. 


This function does not return a value. 


The CheckDlgButton function sends a BM_SETCHECK message to the 
specified button control in the given dialog box. 


CheckRadioButton, IsDigButtonChecked 


BOOL CheckMenultem(hmenu, idCheckltem, uCheck) 


HMENU hmenu; 
UINT idCheckltem; 
UINT uCheck; © 


Parameters | 


/* handle of menu */ 
/* menu-item identifier */ 
/* check state and position a 


The CheckMenultem function selects (places a check mark next to) or clears (re- 
moves a check mark from) a specified menu item in the given pop-up menu. 


hmenu 
Identifies the menu. 


idCheckItem 
Identifies the menu item to be selected or cleared. — 


uCheck 
Specifies how to determine the position of the menu item 
(MF_BYCOMMAND or MF_BYPOSITION) and whether the item 
should be selected or cleared (MF_CHECKED or MF_UNCHECKED). This 
parameter can be a combination of these values, which can be combined by 
using the bitwise OR operator. The values are described as follows: 
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Value - Meaning 


MF_BYCOMMAND Specifies that the idCheckItem parameter gives the menu- 
item identifier (MF_BYCOMMAND is the default). 


MF_BYPOSITION Specifies that the idCheckItem parameter gives the posi- 
tion of the menu item (the first item is at position zero). 
MF_CHECKED Selects the item (adds check mark). 


MF_ UNCHECKED Clears the item (removes check mark). 


Return Value The return value specifies the previous state of the item—-MF_CHECKED or 
MF_UNCHECKED—1f the function is successful. The return value is —1 if the 
menu item does not exist. 


Comments The idChecklItem parameter may identify a pop-up menu item as well as a menu 
item. No special steps are required to select a pop-up menu item. 


Top-level menu items cannot have a check. 


A pop-up menu item should be selected by position since it does not have a menu- © 
item identifier associated with it. 


— See Also _ GetMenuState, SetMenultemBitmaps 


_ CheckRadioButton vot 8 dag 


void CheckRadioButton(hwndDlg, idFirstButton, idLastButton, idCheckButton) 


HWND hwndDig; /* handle of dialog box _ +) 
int idFirstButton; /* identifier of first radio button in group i 
int idLastButton; _—‘/* identifier of last radio button in group +). 
int idCheckButton; /* identifier of radio button to select */ 


The CheckRadioButton function selects (adds a check mark to) a given radio but- 
ton in a group and clears (removes a check mark from) all other radio buttons in 
the group. ; 


Parameters = = hwndDig — | ee ig : 
Identifies the dialog box that contains the radio button. 


idFirstButton | | 
Specifies the identifier of the first radio button in the group. 


idLastButton | 
Specifies the identifier of the last radio button in the group. 
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idCheckButton 
Specifies the identifier of the radio button to select. 
Return Value This function does not return a value. 
Comments The CheckRadioButton function sends a BM_SETCHECK message to the 


specified radio button control in the given dialog box. 


See Also CheckDlgButton, IsDlgButtonChecked 
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HWND Child WindowFromPoint(hwndParent, pt) 
HWND hwndParent; /* handle of parent window i a 
POINT pt; /* structure with point coordinates si 


The Child WindowFromPoint function determines which, if any, of the child win- 
dows belonging to the given parent window contains the specified point. | 


Parameters hwndParent 
Identifies the parent window. 
pt | : | 
Specifies a POINT structure that defines the client coordinates of the point to 
be checked. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the M ee Windows Program- 
mer’s Reference, Volume 3. 


Return Value . The return value is the handle of the child window (hidden, disabled, or trans- 
| parent) that contains the point, if the function is successful. If the given point lies 
outside the parent window, the return value is NULL. If the point is within the 
parent window but is not contained within any child window, the return 1 value 1 iS 
the handle of the parent window. - | 


Comments More than one window may contain the given point, but Windows returns the 
3 handle only of the first window encountered that contains the point. 
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See Also WindowFromPoint 


ChooseColor | rs 


#include <commdlg.h> 


BOOL ChooseColor(/pcc) | | 
CHOOSECOLOR FAR* Ipcc; /* address of structure with initialization data */ 


The ChooseColor function creates a system-defined dialog box from which the 
user can select a color. 


Parameters Ipcc 
Points to a CHOOSECOLOR structure that initially contains information nec- 
essary to initialize the dialog box. When the ChooseColor function returns, this 
structure contains information about the user’s color selection. The CHOOSE- 
COLOR structure has the following form: 


#include <commd1lg.h> 


typedef struct tagCHOOSECOLOR { /* cc */ 
DWORD 1StructSize; 
HWND hwndOwner ; 
HWND hInstance; 
COLORREF rgbResult; 
COLORREF FAR* 1lpCustColors; 
DWORD Flags; 
LPARAM 1CustData; 
UINT (CALLBACK* IpfnHook)(HWND, UINT, WPARAM, LPARAM); 
LPCSTR IpTemplateName; 
} CHOOSECOLOR; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. It is zero if an error oc- 
curs, if the user chooses the Cancel button, or if the user chooses the Close com- 
mand on the System menu (often called the Control menu) to close the dialog box. 


Errors Use the CommDIgExtendedError function to retrieve the error value, which may | 
#e be one of the following: 


CDERR_FINDRESFAILURE 
CDERR_INITIALIZATION 
CDERR_LOCKRESFAILURE 
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Comments 


Example 


CDERR_LOADRESFAILURE 
CDERR_LOADSTRFAILURE 
CDERR_MEMALLOCFAILURE 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK 
CDERR_NOTEMPLATE 
CDERR_STRUCTSIZE 


The dialog box does not support color palettes. The color choices offered by the 
dialog box are limited to the system colors and dithered versions of those colors. 


If the hook function (to which the IpfnHook member of the CHOOSECOLOR 


structure points) processes the WM_CTLCOLOR message, this function must re- 
turn a handle for the brush that should be used to paint the control background. 


The following example initializes a CHOOSECOLOR structure and then creates 


a color-selection dialog box: 


/* Color variables */ | 

CHOOSECOLOR cc; 

COLORREF clr; 

COLORREF acirCust[16]; 

int i; 

/* Set the custom-color controls to white. */ 


for (i = @; i < 16; i++) 
acIrCust[Li] = RGB(255, 255, 255); 


/* Initialize clr to black. #*/ 
clr = RGB(@, @, 0); 
/* Set all structure fields to zero. */ 


memset(&cc, @, sizeof(CHOOSECOLOR)); 


/* Initialize the necessary CHOOSECOLOR members. 


ec. 1StructSize = sizeof (CHOOSECOLOR); 


cc.hwndOwner = hwnd; 
cc.rgbResult = clr; 


~ ec. TpCustColors = aclirCust; 


cc.Flags = CC_PREVENTFULLOPEN; 


* / 
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if (ChooseColor(&cc)) 


. /* Use cc. popRe sure to select Phe user-requested color. */ 


ChooseFont Ae ea aa] 
#include <commdlg.h> 


BOOL ChooseFont(/pcf) Tees | 
~~ CHOOSEFONT FAR*lpcf; /* address of structure with initialization data — */ 


The ChooseFont function creates a system-defined dialog box from which the 
user can select a font, a font style (such as bold or italic), a point size, an effect 
(such as strikeout or underline), and a color. 


Parameters lpcf : 
: Points to a CHOOSEFON T structure that initially contains information 
necessary to initialize the dialog box. When the ChooseF ont function returns, 


this structure contains information about the user’s font selection. The 
~CHOOSEFONT structure has the following form: 


#tinclude <commd1g.h> 


typedef struct tagCHOOSEFONT { /* cf */ 


DWORD 1StructSize; 
HWND : ~ hwndOwner; 
HDC hDC; 
- LOGFONT FAR* TpLogFont; 
int i1PointSize; 
DWORD Flags; 
COLORREF rgbColors; 
LPARAM 1CustData; 3 7 
UINT (CALLBACK* IpfnHook)(CHWND, UINT, WPARAM, LPARAM) ; 
LPCSTR ees TpTemplateName; 
~ HINSTANCE hInstance; 
LPSTR IpszStyle; 
UINT nFontType; 
int nSizeMin; 
int | nSizeMax; 


} CHD SEEONT: 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
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Return Value 


Errors 


Example 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the CommDI]gExtendedError function to retrieve the error value, which may 
be one of the following: 


CDERR_FINDRESFAILURE 
CDERR_INITIALIZATION 
CDERR_LOCKRESFAILURE 
CDERR_LOADRESFAILURE 
CDERR_LOADSTRFAILURE 
CDERR_MEMALLOCFAILURE | 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK 
CDERR_NOTEMPLATE 
CDERR_STRUCTSIZE 
CFERR_MAXLESSTHANMIN 
CFERR_NOFONTS 


The following example initializes a CHOOSEFONT structure and then displays a 
font dialog box: 


LOGFONT If; 
CHOOSEFONT cf; 


/* Set all structure fields to zero. */ 


memset(&cf, @, sizeof (CHOOSEFONT)); 


ef. 1StructSize = sizeof(CHOOSEFONT); 


cf. hwndOwner = hwnd; 

cf.lpLogFont = &lf; 

cf.Flags = CF_SCREENFONTS | CF_EFFECTS; 
cf.rgbColors = RGB(@, 255, 255); /* light blue */ 
cf.nFontType SCREEN_ FONTTYPE; 


ChooseFont(&cf); 


Chord a3 


Chord voce — a 


BOOL Chord(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXStartLine, nYStartLine, 


nXEndLine, nYEndLine) | 
HDC hdc; /* handle of device context i | 
int nLeftRect; /* x-coordinate upper-left corner bounding rectangle : i 
int nTopRect; ———_—S*/* y-coordinate upper-left corner bounding rectangle ‘ey 
int nRightRect; /* x-coordinate lower-right corner bounding rectangle __ */ 
int nBottomRect; /* y-coordinate lower-right corner bounding rectangle — **/ 
int nXStartLine; —«—/* x-coordinate line-segment starting point st 
int nYStartLine; /* y-coordinate line-segment starting point a | 
int nXEndLine; /* x-coordinate line-segment ending point | */ 
int nYEndLine; /* y-coordinate line- segment ending point . sa | 


The Chord function draws a chord (a closed figure bounded by the intersection of 
an ellipse and a line segment). 


Parameters hdc 
Identifies the device context. 


nLeftRect 
Specifies the logical x- -coordinate of the upper en corner of the bounding 
rectangle. | 

nlopRect 
Specifies the logical yegordinate of the upper-left corner of the bounding 
rectangle. 

nRightRect . 
Specifies the logical x-coordinate of the Powerman corner of the bounding 
rectangle. 

nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the bounding 
rectangle. 


nX StartLine 
_ Specifies the logical x-coordinate of the starting point of the line segment. 


ny, StartLine 
Specifies the logical y-coordinate of the starting point of the line segment. 


nXEndLine 
Specifies the logical x-coordinate of the ending point of the line segment. 


nYEndLine | 
species the logical y-coordinate of the ending point of the line segment. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
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Comments 


Example 


See Also 


ClassFirst 


The (nLeftRect, nTopRect) and (nRightRect, nBottomRect) parameter combina- 
tions specify the upper-left and lower-right corners, respectively, of a rectangle 
bounding the ellipse that is part of the chord. The (nXStartLine, nYStartLine) and 
(nXEndLine, nYEndLine) parameter combinations specify the endpoints of a line 
that intersects the ellipse. The chord is drawn by using the selected pen and is 
filled by using the selected brush. 


The figure the Chord function draws extends up to but does not include the right 
and bottom coordinates. This means that the height of the figure is determined as 
follows: 

nBottomRect — nTopRect 


The width of the figure is determined similarly: 


nRightRect — nLeftRect 


The following example uses a RECT structure to store the points defining the 
bounding rectangle and uses POINT structures to store the coordinates that 


specify the beginning and end of the chord: 


HDC hdc; 

RECT rc = { 10, 10, 180, 140 }; 
POINT ptStart = { 12, 12 }; 
POINT ptEnd = { 128, 135 }; 


Chord(hdc, rc.left, rc.top, rc.right, rc.bottom, 
ptStart.x, ptStart.y, ptEnd.x, ptEnd.y); 


Are 


#include <toolhelp.h> 


BOOL ClassFirst(lpce) 
CLASSENTRY FAR [pce; /* address of structure for class info i | 


The ClassFirst function fills the specified structure with general information 


about the first class in the Windows class list. 


Parameters 


Return Value 


Comments 


See Also 


‘ClassNext— 
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lpce — | 
Points to a CLASSENTRY structure that will receive the class information. 
The CLASSENTRY structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagCLASSENTRY { /* ce */ 
DWORD dwSize; 
HMODULE hInst; | 
char szClassNameLMAX_CLASSNAME + 1]; 
WORD wNext; : 
} CLASSENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s RIMES Volume 3. | 


The return value is nonzero if the function is successful. Otherwise, it 1s zero. 


The ClassFirst function can be used to begin a walk through the Windows class — 


list. To examine subsequent items in the class list, an application can use the 
ClassNext function. 


Before calling ClassFirst, an application must initialize the CLASSENTRY struc- 
_ ture and specify its size, in bytes, in the dwSize member. An application can ex- 


amine subsequent entries in the Windows class list by uate the ClassN ext 


function.” 


For more specific information about an individual class, use the GetClassInfo 
function, specifying the name of the class and instance handle from the 
CLASSENTRY structure. 


ClassNext, GetClassInfo | 


#include <toolhelp.h> 


~  BOOL ClassNext(Ipce) : pe ee a 4 | 
_ CLASSENTRY FAR* Ipce; _—‘/* address of structure for class info — */ 


‘The ClassNext function fills the specified structure with general information 
about the next class in the Windows class list. : 
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Parameters Ipce 


Points to a CLASSENTRY structure that will receive the class information. 
The CLASSENTRY structure has the following form: 


fHinclude <toolhelp.h> 


typedef struct tagCLASSENTRY { /* ce */ 
DWORD dwSize; 
HMODULE hInst; 
char szClassName[MAX_CLASSNAME + 1]; 
WORD wNext; 

} CLASSENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value _ The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The ClassNext function can be used to continue a walk through the Windows 
class list started by the ClassFirst function. 


For more specific information about an individual class, use the GetClassInfo 


function with the name of the class and instance handle from the CLASSENTRY 
structure. | 


See Also ClassFirst 


ClearCommBreak x] 


int CleaarCommBreak(idComDev) 
int idComDev; /* device to be restored af 


The ClearCommBreak function restores character transmission and places the 
communications device in a nonbreak state. 


- Parameters idComDev 


Identifies the communications device to be restored. The OpenComm function: 
returns this value. 
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Return Value The return value is zero if the function is successful, or —1 if the idComDev 
| parameter does not identify a valid device. 


Comments This function clears the communications-device break state set by the SetComm- 
Break function. 
See Also OpenComm, SetCommBreak 


ClientToScreen [ex] 


void ClientToScreen(hwnd, [ppt) 
HWND hwnd; _ /* window handle for source coordinates */ 
POINT FAR?® /ppt; /* address of structure with coordinates */ 


The ClientToScreen function converts the client coordinates of a given point on 
the screen to screen coordinates. 


Parameters hwnd 
Identifies the window whose client area is used for the conversion. 
: [ppt | 
Points to a POINT structure that contains the client coordinates to be con- 
verted. The POINT structure has the following form: 


typedef struct tagPOINT { [* pt * / 
int x;3.- 
int y; 
} POINT; 
For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. , 


ReturnValue —‘This function does not return a value. 
Comments The ClientToScreen function replaces the coordinates in the POINT structure © 


with the screen coordinates. The screen coordinates are relative to the upper-left — 
corner of the screen. 
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Example The following example uses the LOWORD and HIWORD macros and the 
ClientToScreen function to convert the mouse position to screen coordinates: 


POINT pt; 


pt.x = LOWORD(1Param) ; 
pt.y = HIWORD(1Param); 
ClientToScreen(hwnd, &pt); 


See Also MapWindowPoints, ScreenToClient 


ClipCursor [2x | 


void ClipCursor(/prc) 
const RECT FAR® I[prc; /* address of structure with rectangle sf 


The ClipCursor function confines the cursor to a rectangle on the screen. If a sub- 
sequent cursor position (set by the SetCursorPos function or by the mouse) lies 
outside the rectangle, Windows automatically adjusts the position to keep the cur- 
sor inside. 


Parameters [prc 
Points to a RECT structure that contains the screen coordinates of the upper- 
left and lower- night corners of the confining rectangle. If this parameter is 
NULL, the cursor is free to move any where on the screen. The RECT structure 
has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value — This function does not return a value. 


Comments The cursor is a shared resource. An application that has confined the cursor to a 
given rectangle must free it before relinquishing control to another application. 


See Also GetClipCursor, GetCursorPos, SetCursorPos 
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CloseClipboard [2x] 


BOOL CloseClipboard(void) 


Parameters 
Return Value 


Comments 


See Also 


CloseComm 


The CloseClipboard function closes the clipboard. 
This function has no parameters. 
The return value is nonzero if the function is successful. Otherwise, it is zero. 


The CloseClipboard function should be called when a window has finished ex- 


amining or changing the clipboard. This lets other applications access the clip- 
board. | 


GetOpenClipboard Window, OpenClipboard 


[ 2.x | 


int CloseComm(idComDev) 


int idComDev; 


Parameters 


Return Value 


See Also 


/* device to close =| 


The CloseComm function closes the specified communications device and frees 
any memory allocated for the device’s transmission and receiving queues. All char- 
acters in the output queue are sent before the communications device is closed. 


idComDev | 
Specifies the device to be closed. The OpenComm function returns this value. 


The return value is zero if the function is successful. Otherwise, it is less than zero. 


OpenComm 


60. CloseDriver 


CloseDriver oe aa [aa] 


LRESULT CloseDriver(hdrvr, lParamI1, lParam2) 


HDRVR hdrvr; /* handle of installable driver */ 
LPARAM /Param1; /* driver-specific data wi 
LPARAM /Param2; /* driver-specific data oo) 


The CloseDriver function closes an installable driver. 


Parameters hdrvr 
Identifies the installable driver to be closed. This parameter must have been ob- 
tained by a previous call to the OpenDriver function. | 


l[Param1 
Specifies driver-specific data. 
[Param2 | 
Specifies driver-specific data. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments When an application calls CloseDriver and the driver identified by hdrvr is the 
last instance of the driver, Windows calls the DriverProc function three times. On 
the first call, Windows sets the third DriverProc parameter, wMessage, to 
DRV_CLOSE; on the second call, Windows sets wMessage to DRV_DISABLE; 
and on the third call, Windows sets wMessage to DRV_FREE. When the driver 
identified by hdrvr is not the last instance of the driver, only DRV_CLOSE is sent. 
The values specified in the /Param1 and [Param2 parameters are passed to the 
/[ParamI and /Param2 parameters of the DriverProc function. 


See Also DriverProc, OpenDriver 


CloseMetaFile - wae 
HMETAFILE CloseMetaFile(/dc) 
HDC hdc; /* handle of device context */ 


The CloseMetaFile function closes a metafile device context and creates a nade 
_ of a metafile. An application can use this handle to play the metafile. 


Parameters hdc 
Identifies the metafile device context to be closed. 
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Return Value The return value is the handle of the metafile if the function is successful. Other- 
wise, itis NULL. 
Comments If a metafile handle created by using the CloseMetaFile function is no longer 


needed, you should remove it (using the DeleteMetaFile function). 


Example | The following example creates a device-context handle of a memory metafile, 
draws a line in the device context, retrieves a handle of the metafile, plays the 
metafile, and finally deletes the metafile. 


HDC hdcMeta; 
HMETAFILE hmf; 


~hdcMeta = CreateMetaFile (NULL); 
MoveTo(hdcMeta, 10, 10); 
LineTo(hdcMeta, 100, 100); 
hmf = CloseMetaFile(hdcMeta); 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf); 


See Also CreateMetaFile, DeleteMetaFile, PlayMetaFile 


CloseSound x] 


void CloseSound(void) 


This function is obsolete. Use the multimedia audio functions instead. For informa- 
tion about these functions, see the Microsoft Windows Multimedia Programmer’s 
Reference. 7 


CloseWindow [2x | 
void CloseWindow(hwnd) | 
HWND hwnd; /* handle of window to minimize */ 


The Close Window function minimizes (but does not destroy) the given window. 
To destroy a window, an application must use the Destroy Window function. 


Parameters hwnd 
| Identifies the window to be minimized. 
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Return Value This function does not return a value. 

Comments This function has no effect if the hwnd parameter identifies a pop-up or child win- 
dow. | 3 . 

See Also Destroy Window, IsIconic, OpenIcon 


CombineRgn a [2x | 


int CombineRgn(hrgnDest, hrgnSrcl, hrgnSrc2, fCombineMode) 


HRGN hregnDest; /* handle of region to receive combined regions **/ 
HRGN hrgnSrcl; /* handle of first source region | =) 
HRGN hrenSrc2; /* handle of second source region sy | 
int fCombineMode; /* mode for combining regions */ 


The CombineRgn function creates a new region by combining two existing re- 
gions. | 


Parameters hrgnDest 7 | | 2 
Identifies an existing region that will be replaced by the new region. 


hrgnSrcl : 
Identifies an existing region. 
hrgnSrc2 
Identifies an existing region. 


fCombineMode | 
Specifies the operation to use when combining the two source regions. This 
parameter can be any one of the following values: 


Value Meaning | 
RGN_AND _ Uses overlapping areas of both regions (intersection). 
RGN_COPY Creates a copy of region | (identified by the hrgnSrc1 parameter). 
RGN_DIFF Creates a region consisting of the areas of region 1 (identified by 

| hrgnSrc1) that are not part of region 2 (identified by the hrgnSrc2 

parameter). 
RGN_OR _ Combines all of both regions (union). 
RGN_XOR Combines both regions but removes overlapping areas. 
Return Value The return value specifies that the resulting region has overlapping borders 


(COMPLEXREGION), is empty (NULLREGION), or has no overlapping borders 
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(SIMPLEREGION), if the function is successful. Otherwise, the return value is | 
ERROR. 


Comments The size of a region is limited to 32,000 by 32,000 logical units or 64K of 
memory, whichever is smaller. 


The CombineRgn function replaces the region identified by the hrgnDest parame- 
ter with the combined region. To use CombineRgn most efficiently, hrgnDest 
should be a trivial region, as shown in the following example. 


Example — The following example creates two source regions and an empty destination re- 

| gion, uses the CombineRgn function to create a complex region, selects the re- 
gion into a device context, and then uses the PaintRgn function to display the 
region: | 


HDC hdc; 
HRGN hrgnDest, hrgnSrcl, hrgnSrc2; 


hrgnDest = CreateRectRgn(Q0, @, 0, @); 
hrgnSrcl = CreateRectRgn(1@, 10, 110, 110); . 
hrgnSrc2 = 


CreateRectRgn(90, 90, 200, 150); 


CombineRgn(hrgnDest, hrgnSrcl, hrgnSrc2, RGN_OR); 
SelectObject(hdc, hrgnDest); 
PaintRgn(hdc, hrgnDest); 


See Also CreateRectRgn, PaintRgn 


CommbDigExtendedError [3.1 | 


#include <commdlg.h> 
DWORD CommDIigExtendedError(void) 


The CommDIgExtendedError function identifies the cause of the most recent 
error to have occurred during the execution of one of the following common 
dialog box procedures: 


= ChooseColor 

= ChooseFont 

= FindText 

= GetFileTitle 

= GetOpenFileName 
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Parameters 


Return Value 


Comments | 


=» GetSaveFileName 
=s PrintDig 
= ReplaceText 


This function has no parameters. 


The return value is zero if the prior call to a common dialog box procedure was 
successful. The return value is CDERR_DIALOGFAILURE if the dialog box 
could not be created. Otherwise, the return value is a nonzero integer that identi- 
fies an error condition. 


Following are the possible CommDI]gExtendedError return values and the mean- 


— ing of each: 

Value | Meaning 

CDERR_FINDRESFAILURE Specifies that the common dialog box proce- 
dure failed to find a specified resource. 

CDERR_INITIALIZATION | Specifies that the common dialog box proce-. 
dure failed during initialization. This error often 

| occurs when insufficient memory is available. 

CDERR_LOADRESFAILURE Specifies that the common dialog box proce- 
dure failed to load a specified resource. 

CDERR_LOCKRESFAILURE Specifies that the common dialog box proce- 

| dure failed to lock a specified resource. 
CDERR_LOADSTRFAILURE Specifies that the common dialog box proce- 


dure failed to load a specified string. 


CDERR_MEMALLOCFAILURE Specifies that the common dialog box proce- 
dure was unable to allocate ey for internal 


structures. 
CDERR_MEMLOCKFAILURE Specifies that the common dialog box proce- 
dure was unable to lock the memory associated 
| with a handle. 
CDERR_NOHINSTANCE Specifies that the ENABLETEMPLATE flag 


was set in the Flags member of a structure for 

the corresponding common dialog box but that 
the application failed to provide a correspond- 

ing instance handle. 


CDERR_NOHOOK Specifies that the ENABLEHOOK flag was set 
| in the Flags member of a structure for the corre- 
sponding common dialog box but that the appli- 
cation failed to provide a pointer to a 
corresponding hook function. 


Value 
CDERR_ NOTEMPLATE 


CDERR_REGISTERMSGFAIL 
CDERR_STRUCTSIZE 


CFERR_NOFONTS 
CFERR_MAXLESSTHANMIN 


FNERR_BUFFERTOOSMALL 


FNERR_INVALIDFILENAME 
FNERR_SUBCLASSFAILURE 


FRERR_BUFFERLENGTHZERO 
PDERR_CREATEICFAILURE 


PDERR_DEFAULTDIFFERENT 
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Meaning 


Specifies that the ENABLETEMPLATE flag 
was set in the Flags member of a structure for 
the corresponding common dialog box but that 
the application failed to provide a correspond- 
ing template. 

Specifies that the Register WindowMessage 
function returned an error value when it was 
called by the common dialog box procedure. 
Specifies as invalid the IStructSize member of 
a structure for the corresponding common 
dialog box. 

Specifies that no fonts exist. 

Specifies that the size given in the nSizeMax 
member of the CHOOSEFONT structure is 
less than the size given in the nSizeMin mem- 


ber. 


Specifies that the filename buffer is too small. 


_ (This buffer is pointed to by the IpstrFile mem- 


ber of the structure for a common dialog box.) 
Specifies that a filename is invalid. 


Specifies that an attempt to subclass a list box 
failed due to insufficient memory. 


Specifies that a member in a structure for the 
corresponding common dialog box points to an 
invalid buffer. 


Specifies that the PrintDlg function failed 
when it attempted to create an information con- 
text. 


Specifies that an ssieien has called the 
PrintDlg function with the 
DN_DEFAULTPRN flag set in the wDefault 
member of the DEVNAMES structure, but the 
printer described by the other structure mem- 
bers does not match the current default printer. 
(This happens when an application stores the 
DEVNAMES structure and the user changes 
the default printer by using Control Panel.) 


To use the printer described by the DEV- 
NAMES structure, the application should clear 
the DN_DEFAULTPRN flag and call the 
PrintDlg function again. To use the default 
printer, the application should replace the DEV- 
NAMES structure (and the DEVMODE struc- 
ture, if one exists) with NULL; this selects the 
default printer automatically. 
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See Also 


CopyCursor 


Value 


PDERR_DNDMMISMATCH 


PDERR_GETDEVMODEFAIL 


PDERR_INITFAILURE 


PDERR_LOADDRVFAILURE 


PDERR_NODEFAULTPRN 
PDERR_NODEVICES 
PDERR_PARSEFATLURE 


PDERR_PRINTERNOTFOUND 


PDERR_RETDEFFAILURE 


PDERR_SETUPFAILURE 


Meaning 


Specifies that the data in the DEVMODE and 


~ DEVNAMES structures describes two different 


printers. 


Specifies that the printer driver failed to initial- 
ize a DEVMODE structure. (This error value 


applies only to printer drivers written for Win- 


dows versions 3.0 and later.) | 
Specifies that the PrintDlg function failed 
during initialization. 

Specifies that the PrintDlg function failed to 
load the device driver for the specified printer. 
Specifies that a default printer does not exist. 
Specifies that no printer drivers were found. 


Specifies that the PrintDlg function failed to 
parse the strings in the [devices] section of the 
WIN.INI file. 

Specifies that the [devices] section of the 
WIN.INI file did not contain an entry for the re- 
quested printer. 

Specifies that the PD_RETURNDEFAULT 
flag was set in the Flags member of the 
PRINTDLG structure but that either the hDev- 
Mode or hDevNames member was nonzero. 
Specifies that the PrintDlg function failed to 
load the required resources. 


For more information about the CommDIgExtendedError function, see the 


Microsoft Windows Programmer’s Reference, Volume 1. 


ChooseColor, ChooseF ont, FindText, GetFileTitle, GetOpenFileName, 
GetSaveFileName, PrintDlg, ReplaceText 


HCURSOR CopyCursor(hinst, heur) 


HINSTANCE hinst; — 


HCURSOR hcur; 


/* handle of application instance a 
/* handle of cursor to copy 


7 


_ The CopyCursor function copies a cursor. 
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Parameters 


Return Value 


Comments 


See Also | 


Copyicon 


hinst 
Identifies the instance of the module that will copy the cursor. 


heur | 
Identifies the cursor to be copied. 


The return value is the handle of the duplicate cursor if the function is successful. 
Otherwise, it is NULL. 7 


When it no 5 tone: requires a cursor, an application must destroy the cursor, using 
the DestroyCursor function. 


The CopyCursor function allows an application or dynamic-link library to accept 
a cursor from another module. Because all resources are owned by the module in 
which they originate, a resource cannot be shared after the module is freed. Copy- 
Cursor allows an application to create a copy that the application then owns. 


Copylcon, DestroyCursor, GetCursor, SetCursor, ShowCursor 


| HICON Copylcon(hinst, hicon) 


-HINSTANCE hinst; 
~ HICON hicon; 


Parameters 


~ Return Value 


Comments 


/* handle of application instance **/ 
/* handle of icon to copy si 


The Copylcon function copies an icon. 


hinst 
Identifies the instance of the module that will copy the icon. 


hicon 


Identifies the icon to be copied. 


The return value is the handle of the duplicate icon if the function is successful. 


Otherwise, it is NULL. 


When it no longer requires an icon, an application should destroy the 1 icon, using 


the westroyicos function. 
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See Also 


CopyLZFile 


The CopylIcon function allows an application or dynamic-link library to accept an 
icon from another module. Because all resources are owned by the module in 
which they originate, a resource cannot be shared after the module is freed. Copy- 
Icon allows an application to create a copy that the application then owns. 


CopyCursor, DestroyIcon, Drawlcon 


#include <lzexpand.h> 


LONG CopyLZFile(#fSource, hfDest) 


HFILE hfSource; 
HFILE hfDest; 


Parameters | 


Return Value 


/* handle of source file */ 
/* handle of destination file */ 


The CopyLZFile function copies a source file to a destination file. If the source 
file is compressed, this function creates a decompressed destination file. If the 
source file is not compressed, this function duplicates the original file. 


hfSource 
Identifies the source file. 


hfDest 


Identifies the destination file. 


The return value specifies the size, in bytes, of the destination file if the function is 
successful. Otherwise, it is an error value less than zero; it may be one of the fol- 
lowing: 


Value | Meaning 
LZERROR_BADINHANDLE The handle identifying the source file was not 
| —-valid. . 

LZERROR_BADOUTHANDLE The handle identifying the destination file was 

— not valid. | | 
LZERROR_READ The source file format was not valid. 
LZERROR_WRITE There is insufficient space for the output file. 
LZERROR_GLOBALLOC There is insufficient memory for the required 

buffers. 7 7 

LZERROR_UNKNOWNALG The file was compressed with an unrecognized 


compression algorithm. 


Comments 


Example 


See Also 
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This function is identical to the LZCopy function. 


The CopyLZFile function is designed for copying or decompressing multiple 
files, or both. To allocate required buffers, an application should call the LZStart 
function prior to calling CopyLZFile. To free these buffers, an application should 
call the LZDone function after copying the files. 


If the function is successful, the file identified by hfDest is decompressed. 


If the source or destination file is opened by using a C run-time function (rather 
than by using the _lopen or OpenFile function), it must be opened in binary mode. 


The following example uses the CopyLZFile function to create copies of four text 
files: 


#tdefine STRICT 


#Hinclude <windows.h> 
#Hinclude <1lzexpand.h> 


#define NUM FILES 4 


char *SzSrc[NUM_FILES] = 
{"readme.txt", "data.txt", "update.txt", "list.txt"}; 
char *szDest[NUM_FILES] = | 
{"readme.bak", "“data.bak", "update.bak", "list.bak"}; 
OFSTRUCT ofStrSrc; — | | pte 
OFSTRUCT ofStrDest; | 
HFILE hfSrcFile, hfDstFile; 
int 7; 


/* Allocate internal buffers for the CopyLZFile function. */ 


LZStart(); 


[x Open, copy, and then close the files. */ 


for Ci =.03.1.< NUM-FILES; ire): { rata 
hfSrcFile = LZOpenFile(szSrc[Li], &ofStrSrc, OF_READ); 
hfDstFile = LZOpenFile(szDest[Li], &ofStrDest, OF_CREATE); 
CopyLZFile(hfSrcFile, hfDstFile); 7 | 
LZClose(hfSrcFile); , 
LZClose(hfDstFile); 


J 


LZDone(); /* free the internal buffers */ 


_lopen, LZCopy, LZDone, LZStart, OpenFile 
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CopyMetaFile — 


HMETAFILE CopyMetaFile(hmfSrc, lpszFile) 
HMETAFILE hmfSrc; _—_—s//* handle of metafile to copy */ 
LPCSTR IpszFile; /* address of name of copied metafile i 


The CopyMetaFile function copies a source metafile to a specified file and re- 
turns a handle of the new metafile. 


Parameters hmfSre 
Identifies the source metafile to be copied. 


IpszFile 
Points to a null- terminated string that specifies the filename of the copied meta- 
file. If this value is NULL, the source metafile is copied to a memory metafile. 


Return Value The return value is the handle of the new metafile if the Fanctiont is successful. 
Otherwise, it is NULL. 


Example The following example copies a metafile to a specified file, plays the copied meta- 
file, retrieves a handle of the copied metafile, changes the position at which the 
metafile is played 200 logical units to the right, and then pays the metafile at the 
new location: 


HANDLE hmf, hmfSource, hmf0ld; 
LPSTR IpszFilel = "MFTest"; 


hmf = CopyMetaFile(hmfSource, lpszFilel); 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf); 


hmfOld = GetMetaFile(IpszFilel); 
SetWindowOrg(hdc, -200, @); 
PlayMetaFile(hdc, hmf0ld); 


DeleteMetaFile(hmfSource); 
DeleteMetaFile(hmf0ld) ; 


See Also GetMetaFile, PlayMetaFile, SetWindowOrg 
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CopyRect | [ 2.x | 


void CopyRect(lprcDst, lprcSrc) 
RECT FAR#® IprcDst;__ /* address of struct. for destination rect. sa 
const RECT FAR® IprcSrc; /* address of struct. with source rect. a 


The CopyRect function copies the dimensions of one rectangle to another. 


Parameters lprcDst 
Points to the RECT structure that will receive the dimensions of the s source 
rectangle. The RECT structure has the following form: | 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


[prcSre 
Points to the RECT structure whoae dimensions are to be age 
Return Value This function does not return a value. 


see Also SetRect 


—CountClipboardFormats wee x] 
int CountClipboardFormats(void) 


The CountClipboardFormats function retrieves the number of different data for- 
mats currently i in the clipboard. 


Parameters — This function has no parameters. 


-ReturnValue == Thereturn value specifies the number of different data formats in n the clipboard, if | 
the function is successful. : 


See Also EnumClipboardFormats | 
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CountVoiceNotes a aa 


int Count VoiceNotes(nvoice) 
int nvoice; /* sound queue to be counted sf | 


This function is obsolete. Use the multimedia audio functions instead. For informa- 
tion about these functions, see the Microsoft Windows Multimedia Programmer’s 
Reference. 


CPlApplet [3.1 


LONG CALLBACK* CPIApplet(hwndCPIl, iMessage, lParam1, |[Param2) 


HWND hwndCPI; /* handle of Control Panel window */ 
UINT iMessage; /* message **/ 
LPARAM [Param]; /* first message parameter a 
LPARAM [Param2; /* second message parameter if 


The CPlApplet function serves as the entry point for a Control Panel dynamic- 
link library (DLL). This function is supplied by the application. 


Parameters hwndCPI 
Identifies the main Control Panel window. 
iMessage 
Specifies the message being sent to the DLL. 


[Param 
Specifies 32 bits of additional message-dependent information. 


lParam2 
Specifies 32 bits of additional message-dependent information. 


Return Value The return value depends on the message. For more information, see the descrip- 
tions of the individual Control Panel messages in Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Comments Use the hwndCPI parameter for dialog boxes or other windows that require a 
handle of a parent window. 


CreateBitmap 73 


CreateBitmap __ oe [2x | 


HBITMAP CreateBitmap(nWidth, nHeight, cbPlanes, cbBits, lpvBits) 
*k 


int nWidth; /* bitmap width 

int nHeight; _/* bitmap height : | mi | 

UINT cbPlanes; /* number of color planes =k 

UINT cbBits; /* number of bits per pixel oe] 

const void FAR* [pvBits; /* address of array with bitmap bits | 
The CreateBitmap function creates a device-dependent memory bitmap that has 
the specified width, height, and bit pattern. 

Parameters nWidth 

| Specifies the width, in pixels, of the bitmap. 

nHeight 


Return Value 


Comments 


Specifies the height, in pixels, of the bitmap. 


cbPlanes 
Specifies the number of color planes in the bitmap. The number of bits per 
plane is the product of the plane’s width, height, and bits per pixel (n width x 
nHeight x cbBits). 


cbBits 
Specifies the number of color bits per display pixel. 


lpvBits 
Points to an array of short integers that contains the initial bitmap bit values. If 
this parameter is NULL, the new bitmap is left uninitialized. For more informa- 
tion about these bit values, see the description of the bmBits member of the 
BITMAP structure in the Microsoft Windows Programmer’s Reference, 
Volume 3. 


The return value is the handle of the bitmap if the function is successful. Other- 
wise, it is NULL. | 


The bitmap created by the CreateBitmap function can be selected as the current 
bitmap for a memory device context by using the SelectObject function. : 


For a color bitmap, either the cbPlanes or cbBits parameter should be set to 1 Th. | 
both of these parameters are set to 1, CreateBitmap creates a monochrome bit- _ 
map. | 


Although a bitmap cannot be copied directly toa display device, the BitBlt func- 


tion can copy it from a memory device context (in which it is the current bitmap) | 
to any compatible device context, including a screen device context. 
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Example 


See Also 


When it has finished using a bitmap created by CreateBitmap, an application 
should select the bitmap out of the device context and then remove the bitmap by 
using the DeleteObject function. 


The following example uses the CreateBitmap function to create a bitmap with a 
zigzag pattern and then uses the PatBIt function to fill the client area with that pat- 
tern: 


HDC hdc; 

HBITMAP hbmp;_ 

HBRUSH hbr, hbrPrevious; 
RECT rc; 


int aZigzag[] = { OxFF, @xF7, @xEB, OxDD, @xBE, Ox7F, OxFF, OxFF }; 


hbmp = CreateBitmap(8, 8, 1, 1, aZigzag); 
hbr = CreatePatternBrush(hbmp) ; 


hdc = GetDC(hwnd); 
UnrealizeObject(hbr); 

hbrPrevious = SelectObject(hdc, hbr); 
GetClientRect(hwnd, &rc); 


PatBlt(hdc, rc.left, rc.top, 

rce.right - rc.left, rc.bottom - rc.top, PATCOPY); 
SelectObject(hdc, hbrPrevious) ; 
ReleaseDC( hwnd, hdc); 


DeleteObject(hbr); 
DeleteObject(hbmp) ; 


BitBlt, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, 
CreateDiscardableBitmap, DeleteObject, SelectObject 


CreateBitmapIindirect | | 2.x | 


HBITMAP CreateBitmapIndirect(ipbm) | 
BITMAP FAR* Ipbm; /* address of structure with bitmap information a 


The CreateBitmapIndirect function creates a bitmap that has the width, height, 
and bit pattern specified in a BITMAP structure. | 


Parameters 


Return Value 


Comments 


Example 
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lpbm 
Points to a BITMAP structure that contains information about the bitmap. The 
BITMAP structure has the following form: 


typedef struct tagBITMAP { /* bm */ 


int bmType; 

int bmWidth; 

int bmHeight; 

int ~ bmWidthBytes; 


BYTE bmPlanes; 
BYTE bmBitsPixel; 
void FAR* bmBits; 

} BITMAP; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


The return value is the handle of the bitmap if the function is successful. Other- 


wise, it is NULL. 


Large bitmaps cannot be displayed on a display device by copying them directly to 


the device context for that device. Instead, applications should create a memory 
device context that is compatible with the display device, select the bitmap as the 
current bitmap for the memory device context, and then use a function such as 
BitBlt or StretchBlt to copy it from the memory device context to the display 
device context. (The PatBlt function can copy the bitmap for the current brush 
directly to the display device context.) 


When an application has finished using the bitmap created by the Create- 
BitmapIndirect function, it should select the bitmap out of the device context and 
then delete the bitmap by using the DeleteObject function. 


If the BITMAP structure pointed to by the Jpbm parameter has been filled in by 
using the GetObject function, the bits of the bitmap are not specified, and the bit- © 
map is uninitialized. To initialize the bitmap, an application can use a function 
such as BitBlt or SetDIBits to copy the bits from the bitmap identified by the first 
parameter of GetObject to the bitmap created by CreateBitmapIndirect. 


The following example assigns values to the members of a BITMAP structure and 
then calls the CreateBitmapIndirect function to create a bitmap handle: 


BITMAP bm; 
HBITMAP hbm; 


int aZigzag[] a4 @xFF, @xF7, @xEB, @xDD, @xBE, Qx7F, OxFF, OxFF }; 
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bm.bmType = @; 
bm.bmWidth = 8; _ 
bm. bmHeight = 8; 
bm.bmWidthBytes = 2; 
bm.bmPlanes = 1; 
bm.bmBitsPixel = 1; 
bm. bmBits = aZigzag; 


hbm = CreateBitmapIndirect(&bm) ; 


See Also BitBlt, CreateBitmap, CreateCompatibleBitmap, CreateDIBitmap, 
CreateDiscardableBitmap, DeleteObject, GetObject 


CreateBrushindirect | 2.x | 


HBRUSH CreateBrushIndirect(/p/b) 
LOGBRUSH FAR*® [plb; /* address of structure with brush attributes sa 


The CreateBrushIndirect function creates a brush that has the style, color, and 
pattern specified ina LOGBRUSH structure. The brush can subsequently be 
selected as the current brush for any device. 


Parameters Iplb 
Points to a LOGBRUSH structure that contains information about the brush. 
The LOGBRUSH structure has the following form: 


typedef struct tagLOGBRUSH { /* |b */ 


UINT TbStyle; 

COLORREF 1bColor; 

int | bHatch; 
} LOGBRUSH; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value | The return value is the handle of the brush if the function is successful. Otherwise, 
itis NULL. ) 
Comments A brush created by using a monochrome (one plane, one bit per pixel) bitmap is 


_ drawn by using the current text and background colors. Pixels represented by a bit 
set to 0 are drawn with the current text color, and pixels represented by a bit set to 
1 are drawn with the current background color. 


Example 


See Also 


CreateCaret | 


CreateCaret 77 


When it has finished using a brush created by CreateBrushIndirect, an applica- 
tion should select the brush out of the device context in which it was used and then 
remove the brush by using the DeleteObject function. 


The following example creates a hatched brush with red diagonal hatch marks and 
uses that brush to fill a rectangle: 


LOGBRUSH 1b; 
HBRUSH hbr, hbrOld; 


BS_ HATCHED; 


lb. 1bStyle = 
1b. 1bColor = RGB(255, 0, 0); 
lb. 1 bHatch = HS_BDIAGONAL; 


hbr = CreateBrushIndirect(&lb); 
hbrOld = SelectObject(hdc, hbr); 
Rectangle(hdc, @, 0, 100, 100); 


CreateDIBPatternBrush, CreatePatternBrush, CreateSolidBrush, Delete- 
Object, GetStockObject, SelectObject 


void CreateCaret(hwnd, hbmp, nWidth, nHeight) 


HWND hwnd; 
HBITMAP hbmp; 
int nWidth; 

int nHeight; 


Parameters | 


/* handle of owner window =) 
/* handle of bitmap for caret shape */ 
/* caret width **/ 
/* caret height i 


The CreateCaret function creates a new shape for the system caret and assigns 
ownership of the caret to the given window. The caret shape can be a line, block, 
or bitmap. 


hwnd - 
Identifies the window that owns the new caret. 

hbmp | 
Identifies the bitmap that defines the caret shape. If this parameter is NULL, the 
caret is solid; if the parameter is 1, the caret is gray. 


nWidth | 


Specifies the width of the caret in logical units. If this parameter is NULL, the 
width is set to the system-defined window-border width. | 
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Return Value 


Comments 


Example 


See Also 


iieihe: 
Specifies the neiahie of the caret, in logical units. if this parameter is NULL, the 
height is set to the system-defined window-border height. 


This function does not return a value. 


If the hbmp parameter contains a bitmap handle, the nWidth and nHeight parame- 
ters are ignored; the bitmap defines its own width and height. (The bitmap handle 
must have been created by using the CreateBitmap, CreateDIBitmap, or Load- 
Bitmap function. d If hbmp is NULL or 1, nWidth and nHeight give the caret’s 
width and height, in logical units; the exact width and height (in pixels) depend on 
the window’s mapping mode. 


The CreateCaret function automatically destroys the previous caret shape, if any, 
regardless of which window owns the caret. Once created, the caret is initially hid- 
den. To show the caret, use the ShowCaret function. 


The system caret is a shared resource. A window should create a caret only when 
it has the input focus or is active. It should destroy the caret before losing the input 
focus or becoming inactive. 


The system’s window-border width or height can be retrieved by using the 
GetSystemMetrics function, specifying the SM_CXBORDER and 
SM_CYBORDER indices. Using the window-border width or height guarantees 
that the caret will be visible on a high-resolution screen. 


The feltowiie example creates a caret, sets its initial position, and then displays 
the caret: 


case WM_SETFOCUS: | 
CreateCaret(hwndParent, NULL, CARET_WIDTH, CARET_HEIGHT); 
SetCaretPos(CARET_XPOS, CARET_YPOS); | 
ShowCaret(hwndParent) ; 
break; 


CreateBitmap, CreateDIBitmap, DestroyCaret, GetSystemMetrics, 
LoadBitmap, ShowCaret 
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CreateCompatibleBitmap — [ 2.x | 


HBITMAP CreateCompatibleBitmap(hdc, nWidth, nHeight) 


HDC hdc; 
int nWidth; 
int nHeight; 


Parameters 


Return Value 


Comments 


/* handle of device context */ 
/* bitmap width **/ 


/* bitmap height ial 


The CreateCompatibleBitmap function creates a bitmap that is compatible with 
the given device. 


hdc - 
Identifies the device context. 


nWidth 
Specifies the width, in bits, of the bitmap. 


nHeight 
Specifies the height, in bits, of the bitmap. 


The return value is the handle of the bitmap if the function is successful. Other- 
wise, it is NULL. 


The bitmap created by the CreateCompatibleBitmap function has the same num- 


~ ber of color planes or the same bits-per-pixel format as the given device. It can be | 


selected as the current bitmap for any memory device that is compatible with the 


— one identified by hdc. 


If hdc identifies a memory device context, the bitmap returned has the same for- 
mat as the currently selected bitmap in that device context. A memory device con- 
text is a memory object that represents a screen surface. It can be used to prepare 
images in memory before copying them to the screen surface of the compatible 
device. | 


When a memory device context is created, the graphics device interface (GDI) 
automatically selects a monochrome stock bitmap for it. 


Since a color memory device context can have either color or monochrome bit- 
maps selected, the format of the bitmap returned by the CreateCompatible- 

Bitmap function is not always the same; however, the format of a compatible . 
bitmap for a non—memory device context is always in the format of the device. 


When it has finished using a bitmap created by CreateCompatibleBitmap, an ap- 
plication should select the bitmap out of the device context and then remove the 
bitmap by using the DeleteObject function. 
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~ Example The following example shows a function named DuplicateBitmap that accepts the 

handle of a bitmap, duplicates the bitmap, and returns a handle of the duplicate. 
This function uses the CreateCompatibleDC function to create source and desti- _ 
nation device contexts and then uses the GetObject function to retrieve the dimen- 
sions of the source bitmap. The CreateCompatibleBitmap function uses these 
dimensions to create a new bitmap. When each bitmap has been selected into a 
device context, the BitBlt function copies the bits from the source bitmap to the 
new bitmap. (Although an application could use the GetDIBits and SetDIBits 
functions to duplicate a bitmap, the method illustrated in this example is much 
faster.) 
HBITMAP PASCAL DuplicateBitmap(HBITMAP hbmpSrc) 
{ 

HBITMAP hbmpOldSrc, hbmpOldDest, hbmpNew; 

HDC hdcSrc, hdcDest; 

BITMAP bmp; 


hdcSrc = CreateCompatibleDC(NULL); 
hdcDest = CreateCompatibleDC(hdcSrc); 


GetObject(hbmpSrc, sizeof(BITMAP), &bmp); 
hbmpOldSrc = SelectObject(hdcSrc, hbmpSrc); 


hbmpNew = CreateCompatibleBitmap(hdcSrc, bmp. bmWidth, 
bmp. bmHei ght); | 


hbmpOldDest = SelectObject(hdcDest, hbmpNew) ; 


BitBlt(hdcDest, @, @, bmp. bmWidth, bmp.bmHeight, hdcSrc, @, @, 
SRCCOPY); 


SelectObject(hdcDest, hbmp01dDest); 
SelectObject(hdcSrc, hbmpOldSrc); 


DeleteDC(hdcDest) ; 
DeleteDC(hdcSrc); 


return hbmpNew; 
| | 


See Also | CreateBitmap, CreateBitmapIndirect, CreateDIBitmap, DeleteObject 
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CreateCompatibleDC . | 2.x | 


HDC CreateCompatibleDC (hdc) 
HDC hdc; /* handle of device context */ 


The CreateCompatibleDC function creates a memory device context that is com- 
patible with the given device. | 


An application must select a bitmap into a memory device context to represent a 
screen surface. The device context can then be used to prepare images in memory 
before copying them to the screen surface of the compatible device. 


Parameters hdc : | 
Identifies the device context. If this parameter is NULL, the function creates a — 
memory device context that is compatible with the system screen. 


Return Value — The return value is the handle of the new memory device context if the function is 
successful. Otherwise, it is NULL. 


Comments The CreateCompatibleDC function can be used only to create compatible device 
contexts for devices that support raster operations. To determine whether a device 
supports raster operations, an application can call the GetDeviceCaps function 
with the RC_BITBLT index. | 


GDI output functions can be used with a memory device context only if a bitmap 
has been created and selected into that context. 


When it has finished using a device context created by CreateCompatibleDC, an 
application should free the device context by calling the DeleteDC function. All 
objects selected into the device context after it was created should be selected out 
and replaced with the original objects before the device context is removed. 


Example _ The following example loads a bitmap named Dog, uses the Create- 
CompatibleDC function to create a memory device context that is compatible 
with the screen, selects the bitmap into the memory device context, and then uses 
the BitBlt function to move the bitmap from the memory device context to the 
screen device context: | 


HDC hdc, hdcMemory; 
HBITMAP hbmpMyBitmap, hbmpOld; 
BITMAP bm; 


-hbmpMyBitmap = LoadBitmap(hinst, "MyBitmap”); 
GetObject(hbmpMyBitmap, sizeof(BITMAP), &bm); 
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hdc = GetDC(hwnd); 
hdcMemory = CreateCompatibleDC(hdc); 
hbmpOld = SelectObject(hdcMemory, hbmpMyBitmap) ; 


BitBlt(hdc, 0, 9, bm. bmWidth, bm. bmHeight, hdcMemory, Q, Q@, SRCCOPY); 


— SelectObject(hdcMemory, hbmp01d); 


See Also 


DeleteDC(hdcMemory); 
ReleaseDC( hwnd, hdc); 


DeleteDC, GetDeviceCaps 


CreateCursor 


HCURSOR CreateCursor(hinst, xHotSpot, yHotSpot, nWidth, nHeight, lpvyANDplane, lpvXORplane) 
**/ 


HINSTANCE hinst; /* handle of application instance 
int xHotSpot; /* horizontal position of hot spot | 
int yHotSpot; /* vertical position of hot spot ty 
int nWidth; /* cursor width a 
int nHeight; /* cursor height */ 
const void FAR* /pvANDplane; /* address of AND mask array =) 
const void FAR* [pvXORplane; /* address of XOR mask array */ 
The CreateCursor function creates a cursor that has the specified width, height, 
and bit patterns. 
Parameters hinst 
Identifies the instance of the module that will create the cursor. 
xHotSpot | 
Specifies the horizontal position of the cursor hot spot. 
yHotSpot 
Specifies the vertical position of the cursor hot spot. 
nWidth © | 
‘Specifies the width, in pixels; of the cursor. 
nHeight 
Specifies the height, in pixels, of the cursor. 
[pvANDplane | 


Points to an array of bytes that contains the bit values for the AND mask of the 
cursor. These can be the bits of a device-dependent monochrome bitmap. 


Return Value 


Comments 


See Also 


CreateDC 


#include <print.h> 
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lpvXORplane | 
Points to an array of bytes that contains the bit values for the XOR mask of the 
cursor. These can be the bits of a device-dependent monochrome bitmap. 


The return value is the handle of the cursor 7 the function is successful. Other- 
wise, itis NULL. 


The nWidth and nHeight parameters must specify a width and height supported by 
the current display driver, since the system cannot create cursors of other sizes. An 
application can determine the width and height supported by the display driver by 
calling the GetSystemMetrics function and specifying the SM_CXCURSOR or 
SM_CYCURSOR value. 


Before terminating, an application must call the DestroyCursor function to free 
any system resources associated with the cursor. | 


CreateIcon, DestroyCursor, GetSystemMetrics, SetCursor 


| HDC CreateDC(lpszDriver, lpszDevice, IpszOutput, IlpvInitData) 


LPCSTR I[pszDriver; /* address of driver name */ 
LPCSTR IpszDevice; /* address of device name **/ 
LPCSTR /pszOutput; /* address of filename or port name */ 
const void FAR® lpvInitData; /* address of initialization data **/ 


Parameters 


The CreateDC function creates a device context for the given pete 


- lpszDriver 


Points to a null-terminated string that specifies t the MS-DOS filename (without | 
extension) of the device driver (for example, oe 


 IpszDevice 


Points to a null-terminated string that specifies the name éf the specific device _ 
_ to be supported (for example, Epson FX- 80). This p Patameter is used if the mod- 
ule supports more than one device. _ 


IpszOutput : | 
- Points to a null- tenininated string that specifies the MS- DOS filename or device 
name for the ic nvaie: output medium (file or ee por), 
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Return Value 


Comments 


[pvInitData ae 
Points to a DEVMODE structure that contains device-specific initialization in- 
formation for the device driver. The ExtDeviceMode function retrieves this 
structure already filled in for a given device. The /pvinitData parameter must 
be NULL if the device driver is to use the default initialization (if any) 
specified by the user through Windows Control Panel. 


The DEVMODE structure has the following form: 


#Hinclude <print.h> 


typedef struct tagDEVMODE { /* dm */ 
char dmDeviceName[CCHDEVICENAME]; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDriverExtra; 
DWORD dmFields; 
int dmOrientation; 
int dmPaperSize; 
int dmPaperLength; 
int  dmPaperWidth; 
int dmScale; 
int  dmCopies; 
int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; 
int  dmDuplex; 
int dmY Resolution; 
int dmTTOption; 
} DEVMODE; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the handle of the device context for the specified device if the 
function is successful. Otherwise, it is NULL. 


The PRINT.H header file is required if the DEVMODE structure is used. 


Device contexts created by using the CreateDC function must be deleted by using 


the DeleteDC function. All objects selected into the device context after it was 
created should be selected out and replaced with the original objects before the 


device context is deleted. 


MS-DOS device names follow MS-DOS conventions; an ending colon (:) is rec- 
ommended, but optional. Windows strips the terminating colon so that a device 
name ending with a colon is mapped to the same port as the same name without a 
colon. The driver and port names must not contain leading or trailing spaces. 


Example 
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The following example uses the CreateDC function to create a device context for 


a printer, using information round by the PrintDlg function in a PRINTDLG 


structure: 


PRINTDLG ~~ pd; 


HDC hdc; 

LPDEVNAMES 1pDevNames; 
LPSTR lpszDriverName; 
LPSTR IpszDeviceName; 
-LPSTR IpszPortName; 
i 


See Also 


* PrintDig displays the common dialog box for printing. The 
* PRINTDLG structure should be initialized with appropriate values. 
* / 


PrintDlg(&pd); 

lpDevNames = (LPDEVNAMES) GlobalLock(pd. hDevNames ) ; 

IpszDriverName (LPSTR) TpDevNames + lpDevNames->wDriverOffset; 
IpszDeviceName (LPSTR) IpDevNames + |]pDevNames->wDeviceOffset; 
IpszPortName (LPSTR) IpDevNames + IpDevNames->wOutputOffset; 
GlobalUnlock(pd.hDevNames) ; 

hdc = CreateDC(IpszDriverName, IpszDeviceName, IpszPortName, NULL); 


CreateIC, DeleteDC, ExtDeviceMode, PrintDlg 


CreateDialog 2 i tt—t=tS 


~HWND CreateDialog(hinst, IpszDigTemp, hwndOwner, digprc) 


~ HINSTANCE hinst;  —=——sS/* handle of application instance 3 a) 
LPCSTR I[pszDigTemp; /* address of dialog box template name Se) 
HWND hwndOwner; /* handle of owner window */ 

/* instance address of dialog box procedure sy 


DLGPROC digpre;_ 


Parameters — 


The CreateDialog function creates a modeless dialog box from a dialog box tem- 


plate resource. 


hinst 
Identifies an instance of the module whose executable file contains the dialog 
box template. 


lpszDigTemp 


Points to a null-terminated string that names the é dialda box template. 


~ hwndOwner 


Identifies the window that owns the dialog box. 
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Return Value 


Comments 


Example 


See Also 


dlgprc 
Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog- 
Proc callback function. 


The return value is the handle of the dialog box that was created, if the function is 
successful. Otherwise, it is NULL. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if the DS_SETFONT style 
was specified) and a WM_INITDIALOG message, and then the dialog box is dis- 
played. 


The CreateDialog function returns immediately after creating the dialog box. 


To make the dialog box appear in the owner window upon being created, use the 
WS_VISIBLE style in the dialog box template. 


Use the Destroy Window function to destroy a dialog box created by the Create- 
Dialog function. 


A dialog box can contain up to 255 controls. 


The following example creates a modeless dialog box: 


HWND hwndD1lgFindBox; 
DLGPROC dlgprc = (DLGPROC) MakeProcInstance(FindDlgProc, hinst); 


hwndDIlgFindBox = CreateDialog(hinst, "dlgFindBox", hwndParent, dlgprc); 


CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, 
Destroy Window, MakeProcInstance 


CreateDialogindirect 87 


CreateDialogindirect — - [ 2.x | 


HWND CreateDialogIndirect(hinst, lpvDlgTmp, hwndOwner, dlgprc) 


HINSTANCE hinst; /* handle of application instance */ 
const void FAR* /pyvDigTmp; /* address of dialog box template sa | 
HWND hwndOwner; | /* handle of owner window */ 
DLGPROC digprc; _ /* instance address of dialog box procedure iat 


The CreateDialogIndirect function creates a modeless dialog box from a dialog 
box template in memory. 


Parameters hinst | | 
Identifies the instance of the module that will create the dialog box. 


lpvDigTmp 
Points to a global memory object that contains a dialog box template used to © 
create the dialog box. This template is in the form of a DialogBoxHeader struc- 
ture. For more information about this structure, see Chapter 7, “Resource For- 
mats Within Executable Files,” in the M icrosoft Windows Programmer’ Ss 
Reference, Volume 4. 


hwndOwner 
Identifies the window that owns the dialog box. 


dlgprc : 

Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation, see the description of the DialogProc callback function. 


Return Value The return value is the window handle of the dialog box if the function is success- _ 
ful. Otherwise, it is NULL. 


Comments The CreateWindowEx function is called to create the dialog box. The dialog box | 
procedure then receives a WM_SETFONT message (if the DS_SETFONT style 
was specified) and a WM_INITDIALOG message, and then the oe box 1s dis- | 
played. 


The CreateDialogindtrect TunetOn returns aegis after creating the dialog 
box. | 


To make the dialog box appear in the owner window upon beuig created, use the | 
WS. _VISIBLE style in the dialog box template. 


Use the Destroy Window function to destroy a dialog box created by the Create- 
Dialogindirect function. | 


A dialog box can contain up to 255 controls. 
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Example The following example uses the CreateDialogIndirect function to create a dialog . 
box from a dialog box template in memory: 


DLGPROC dlgprc = (DLGPROC) MakeProcInstance(DialogProc, hinst); 
HWND hdlg; | 
BYTE FAR* 1lpbD1lgTemp; 


. | * Allocate global memory and build a dialog box template. * / 


hdlg = CreateDialogIndirect(hinst, IpbDIlgTemp, hwndParent, dlgprc); 


See Also | CreateDialog, CreateDialogIndirectParam, CreateDialogParam, Destroy- 
Window, MakeProcInstance 


CreateDialogindirectParam 


HWND CreateDialogIndirectParam(hinst, [pvDIlgTmp, hwndOwner, dlgprc, lParamInit) 


HINSTANCE hinst; /* handle of application instance **/ 
const void FAR* /[pvDlgTmp; /* address of dialog box template sf 
HWND hwndOwner; /* handle of owner window | a | 
DLGPROC dlgprc; /* instance address of dialog box procedure = */ 
LPARAM I/ParamlInit; /* initialization value i 


The CreateDialogIndirectParam function creates a modeless dialog box from a 
dialog box template in memory. Before displaying the dialog box, the function 
passes an application-defined value to the dialog box procedure as the /Param pa- 
rameter of the WM_INITDIALOG message. An application can use this value to 
initialize dialog box controls. 


Parameters hinst 
| Identifies the instance of the module that will create the dialog box. 


lpvDIgTmp 
Points to a global memory object that contains a dialog box template used to 
create the dialog box. This template is in the form of a DialogBoxHeader struc- 
ture. For more information about this structure, see Chapter 7, “Resource For- 
mats Within Executable Files,” in the Microsoft Windows Programmer’s | 
Reference, Volume 4. 


Return Value 


Comments 


Example : 
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hwndOwner 
Identifies the window that owns the ales box. 


dlgprc , 

Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation, see the description of the DialogProc callback function. 


lParamInit 
Specifies the value to pass to the dialog box when processing the 
WM_INITDIALOG message. 


The return value is the window handle of the dialog box if the function i iS success- 
ful. Otherwise, it is NULL. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if the DS_SETFONT style 
was specified) ands a WM _INITDIALOG message, and then the dialog box is dis- 
played. 


The CreateDialogIndirectParam function returns immediately after creating the 


dialog box. 


To make the dialog box appear in the owner window upon being creatied, use the : 
WS_VISIBLE style in the dialog box template. : 


Use the Destroy Window function to destroy a dialog box created by the Create- ‘ 


DialogIndirectParam function. 


A dialog box can contain up to 255 controls. 


The following example calls the CreateDialogIndirectParam function to create a 
modeless dialog box from a dialog box template in memory. The example uses the 
/Paramlnit parameter to send two initialization parameters, wInitParm1 and wInit- _ 
Parm2, to the dialog box procedure when the WM SINITDISLOG message 1S 
being processed. 


#tdefine MEM_LENGTH 100 

HGLOBAL hglbDlgTemp; 

BYTE FAR* IpbDIgTemp; - 
DLGPROC digprc = (DLGPROC) MakeProcInstance(DialogProc, hinst); 
HWND hwndD1g; 3 
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/* Allocate a global memory object for the dialog box template. */ 
hgibDigTemp = GlobalAlloc(GHND, MEM_LENGTH); | 

/* Build a DLGTEMPLATE structure in the memory object. */ 
ipbD1gTemp = GlobalLock(hglbD1gTemp) ; 


hwndDig = CreateDialogIndirectParam(hinst, IpbDigTemp, 
hwndParent, digpre, 0); 


See Also CreateDialog, CreateDialogIndirect, CreateDialogParam, Destroy Window, 
MakeProcInstance 


CreateDialogParam a 


HWND CreateDialogParam(hinst, lpszDlgTemp, hwndOwner, dlgprc, lParamInit) 


HINSTANCE hinst; /* handle of application instance a | 
LPCSTR I[pszDigTemp; /* address of name of dialog box template sf 
HWND hwndOwner; /* handle of owner window *] 
DLGPROC digprc; /* instance address of dialog box procedure **/ 
LPARAM /Paraminit; /* initialization value or | 


The CreateDialogParam function creates a modeless dialog box from a dialog 
box template resource. Before displaying the dialog box, the function passes an 
application-defined value to the dialog box procedure as the /Param parameter of 
the WM_INITDIALOG message. An application can use this value to initialize 
dialog box controls. 


Parameters hinst 
Identifies an instance of the module whose executable file contains the snies 


box template. 
lpszDlgTemp 
Points to a null-terminated string that names the dialog box template. 


hwndOwner 
Identifies the window that owns the dialog box. 


dlgprc 
Specifies the procedure-instance address oft the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog- 
Proc callback function. 


Return Value 


Comments 


Example 


See Also 
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[ParamInit 
Specifies the value to pass to the dialog box when eae the 
WM_INITDIALOG message. 


The return value is the handle of the dialog box that was created, if the function is 
successful. Otherwise, it is NULL. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if the DS_SETFONT style _ 
was specified) and a WM_INITDIALOG message, and then the dialog box is dis- 
played. 


The CreateDialogParam function returns immediately after creating the dialog 
box. 


To make the dialog box appear in the owner window upon being created, use the 


‘WS_VISIBLE style in the dialog box template. 


A dialog box can contain up to 255 controls. 


The following example uses the CreateDialogParam function to create a mode- 
less dialog box. The function passes the application-defined flags MIXEDCASE 
and WHOLEWORD, which will be received by the dialog box as the /Param pa- 
rameter of the WM_INITDIALOG message. 


HWND hwndChangeBox; 
DLGPROC dlgprc = (DLGPROC) NakeProcInstance(ChangeD1gProc, hinst); 


hwndChangeBox = CreateDialogParam(hinst, "dlgFindBox", 
hwndParent, eis MIXEDCASE | WHOLEWORD) ; 


CreateDialog, CreateDialogIndirect, Create aaemearecteara Destroy- 
Window 


CreateDIBitmap 


HBITMAP CreateDIBitmap(hdc, Ipbmih, dwInit, IpvBits, lpbmi, fnColorUse) 


HDC hdc; /* handle of device context ; si 
BITMAPINFOHEADER FAR* Ota, /* address of structure with header eG) oe 
DWORD dwinit; /* CBM_INIT to initialize bitmap a 
const void FAR* [pvBits; /* address of array with bitmap values **/ 
BITMAPINFO FAR* ge /* address of structure with bitmap data it 
UINT jfnColorUse; | /* RGB or palette indices ba 
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Parameters 


The CreateDIBitmap function creates a device-specific memory bitmap from a 
device-independent bitmap (DIB) specification and optionally sets bits in the bit- 
map. . 


hdc 
Identifies the device context. 


[pbmih 
Points to a BITMAPINFOHEADER structure that describes the size and for- 
mat of the device-independent bitmap. The BITMAPINFOHEADER structure 
has the following form: 


typedef struct tagBITMAPINFOHEADER { /* bmih */ 
-DWORD biSize; 
LONG biWidth; 
LONG biHeight; 
WORD biPlanes; 
WORD biBitCount; 
DWORD biCompression; 
DWORD biSizeImage; 
LONG bixXPelsPerMeter; 
LONG biYPelsPerMeter; 
DWORD biClrUsed; 
DWORD = biCirImportant; 
} BITMAPINFOHEADER; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


dwlnit 
Specifies whether the memory bitmap is initialized. If this value is CBM_INIT, 
the function initializes the bitmap with the bits specified by the /pvBits and 
[pbmi parameters. 


[pvBits 
Points to a byte array that contains the initial bitmap values. The format of the 
bitmap values depends on the biBitCount member of the BITMAPINFO- 
HEADER structure identified by the /pbmi parameter. 


pe 
Points to a BITMAPINFO structure that describes the diientiche and color 
format of the [pvBits parameter. The BITMAPINFO structure contains a BIT- 
MAPINFOHEADER structure and an array of RGBQUAD structures specify- 
ing the colors in the bitmap. The BITMAPINFO structure has the following 
form: 


fyoeder ctrucs tagBITMAPINFO { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 

} BITMAPINFO; 


Return Value 


Example 
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For a full description of the BITMAPINFO and RGBQUAD structures, see 
the Microsoft Windows Programmer’s Reference, Volume 3. 


jnColorUse 
Specifies whether the bmiColors member of the BITMAPINFO structure 
contains explicit red, green, blue (RGB) values or indices into the currently 
realized logical palette. The fnColorUse parameter must be one of the following 
values: 


Value Meaning 


. DIB_PAL_ COLORS The color table consists of an array of 16-bit indices into 
the currently realized logical palette. 


DIB_RGB_COLORS The color table contains literal RGB values. 


The return value is the handle of the pump if the function is successful. Other- 
wise, it is NULL. 


When it has finished using a bitmap created by CreateDIBitmap, an application 
should select the bitmap out of the device context and then remove the bitmap by 
using the DeleteObject function. 


The following example initializes an array of bits and an array of RGBQUAD 
structures, allocates memory for the bitmap header and color table, fills in the re- 
quired members of a BITMAPINFOHEADER structure, and calls the CreateDI- 
Bitmap function to create a handle of the bitmap: 


HANDLE hloc; 
PBITMAPINFO pbmi; 
HBITMAP hbm; 


BYTE aBits[] = { 0x@0, @x@0, 0x00, 0xeQ, /* bottom row */ 
@x01, Ox12, Ox22, O@xl1l, 
~—6OxO@1l, @xl2, @x22, Ox1l, 
@x0@2, @x20, 0x00, 8x22, 
@x02, Ox20, Ox20, Ox22, 
@x@2, Ox20, Ox00, Ox22, 
@x@1, Ox12, @x22, O@xl1l, . 
Q@x@1, Ox12, Ox22, @x1l }; /* top row * / 


/* blue * / 


RGBQUAD argbgq[] = {{ 255, @, 0, @ }, 
{ @, 255, 0, @ }, /* green * / 
{ 0, 0, 255, O }}; /* red * / 


hloc = LocalAlloc(LMEM_ ZEROINIT | LMEM_ MOVEABLE, 
sizeof(BITMAPINFOHEADER) + (sizeof(RGBQUAD) * 16)); 
pbmi = (PBITMAPINFO) LocalLock(hloc); 
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pbmi->bmiHeader.biSize = sizeof(BITMAPINFOHEADER) ; 
pbmi->bmiHeader.biWidth = 8; 
pbmi->bmiHeader.biHeight = 8; 
pbmi->bmiHeader.biPlanes = 1; 
pbmi->bmiHeader.biBitCount = 4; 

pbmi->bmiHeader.biCompression = BI_RGB; 


memcpy(pbmi->bmiColors, argbq, sizeof(RGBQUAD) * 3); 


hbm = CreateDIBitmap(hdcLocal, (BITMAPINFOHEADER FAR*®) pbmi, CBM_INIT, 
aBits, pbmi, DIB_RGB_COLORS); 
LocalFree(hloc); 


. /* Use the bitmap handle. */ 


DeleteObject(hbm) ; 


See Also CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, Create- 
DiscardableBitmap, DeleteObject 


CreateDIBPatternBrush © : ao 


HBRUSH CreateDIBPatternBrush(hg/bDIBPacked, fnColorSpec) 
HGLOBAL hglbDIBPacked; /* handle of device-independent bitmap */ 
UINT jnColorSpec; /* type of color table */ 


The CreateDIBPatternBrush function creates a brush that has the pattern 
‘specified by a device-independent bitmap (DIB). The brush can subsequently be 
selected for any device that supports raster operations. 


Parameters hglbDIBPacked 
Identifies a global memory object containing a packed device-independent bit- 
map. A packed DIB consists of a BITMAPINFO structure immediately fol- 
lowed by the array of bytes that define the pixels of the bitmap. The 
BITMAPINFO structure has the following form: 


typedef struct tagBITMAPINFO. { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 

} BITMAPINFO; ie ek 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value | 


Comments 


Example 


hrsrc 
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jJnColorSpec 
Specifies whether the bmiColors member(s) of the BITMAPINFO structure 
contain explicit red, green, blue (RGB) values or indices into the currently 
realized logical palette. This parameter must be one of the following values: 


Value Meaning 


DIB_PAL_ COLORS The color table consists of an array of 16-bit indices into 
: | the currently realized logical palette. 


DIB_RGB_ COLORS The color table contains literal RGB values. 


The return value is the handle of the brush if the function is successful. Otherwise, 
itis NULL. 


To retrieve the handle identified by the hglbDIBPacked parameter, an application 


calls the GlobalAlloc function to allocate a global memory object and then fills 


the memory with the packed DIB. 


Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If such a pitta 1S 
larger, Windows creates a fill pattern using only the bits corresponding to the first 
8 rows and 8 columns of pixels in the upper-left corner of the bitmap. | 


When an application selects a two-color DIB pattern brush into a monochrome 
device context, Windows ignores the colors specified in the DIB and instead dis- 
plays the pattern brush, using the current text and background colors of the device _ 
context. Pixels mapped to the first color (at offset 0 in the DIB color table) of the 
DIB are displayed using the text color, and pixels mapped to the second color (at 
offset 1 in the color table) are displayed using the background color. 


When it has finished using a brush created by CreateDIBPatternBrush, an appli- 
cation should remove the brush by using the DeleteObject function. 


The following example retrieves a bitmap named DIBit from the application’s re- 
source file, uses the bitmap to create a pattern brush in a call to the CreateDIB- 
PatternBrush function, selects the brush into a device context, and fills a 
rectangle by using the new brush: 


HRSRC hrsrc; 
HGLOBAL hglbl; 
HBRUSH hbr, hbrOld; 


FindResource(hinst, “DIBit", RI_BITMAP); 
hglbl LoadResource(hinst, hrsre); 
a gee ce 
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See Also 


CreateDiscardableBitmap 


hbr = CreateDIBPatternBrush(hglbl, DIB_RGB_COLORS); 
hbrOld = SelectObject(hdc, hbr); 

Rectangle(hdc, 10, 10, 100, 100); 
UnlockResource(hglbl); 


CreatePatternBrush, DeleteObject, FindResource, GetDeviceCaps, Global- 
Alloc, LoadResource, LockResource, SelectObject, SetBkColor, SetText- 
Color, UnlockResource 


HBITMAP CreateDiscardableBitmap(hdc, nWidth, nHeight) 


HDC hdc; 
int nWidth; 
_ int nHeight; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of device context */ 
/* bitmap width i 
/* bitmap height */ 


The CreateDiscardableBitmap function creates a discardable bitmap that is com- 
patible with the given device. The bitmap has the same number of color planes or 
the same bits-per-pixel format as the device. An application can select this bitmap 


as the current bitmap for a memory device that is compatible with the one iden- 


tified by the hdc parameter. 


hdc 
- Identifies the device context. 


nWidth — 
Specifies the width, in bits, of the ale 


nHeight 
Specifies the height, in bits, of the bitmap 


The return value is the handle of the biihap - the function is successful. Other- 
wise, it is NULL. : | 


Windows can discard a bitmap created by this function only if an application has 
not selected it into a device context. If Windows discards the bitmap when it is not 
selected and the application later attempts to select it, the SelectObject function 
will return zero. | 


Applications should use the DeleteObject function to delete the handle returned 
by the pneoleDecaruabiep Hap function, even if Windows has discarded the 
bitmap. 


CreateBitmap, CreateBitmapIndirect, CreateDIBitmap, DeleteObject 
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CreateEllipticRgn tra 


HRGN CreateEllipticRgn(nLeftRect, nTopRect, nRightRect, nBottomRect) 


int nLeftRect; 
int nTopRect; 
int nRightRect; 
int nBottomRect; 


Parameters 


Return Value 


Comments 


See Also 


CreateEllipticRgnindirect 


/* x-coordinate upper-left corner bounding rectangle oF 
/* y-coordinate upper-left corner bounding rectangle **/ 
/* x-coordinate lower-right corner bounding rectangle 3 
/* y-coordinate lower-right corner bounding rectangle sy 


The CreateEllipticRgn function creates an elliptical region. 


nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle of the ellipse. 

nlTopRect 
Specifies the logical y-coordinate of the upper-left corner of the bounding 
rectangle of the ellipse. 

nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the bounding 
rectangle of the ellipse. 


nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the bounding 
rectangle of the ellipse. 


The return value is the handle of the region if the function is successful. Other- 
wise, itis NULL. 


The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When it has finished using a region created by using the CreateEllipticRgn func- 
tion, an application should remove it by using the DeleteObject function. 


CreateEllipticRgnIndirect, DeleteObject, PaintRgn 


| HRGN CreateEllipticRgnIndirect(iprc) 
const RECT FAR* /prc;__ /* address of structure with pounding rectangle =, =| 


The CreateEllipticRgnIndirect function creates an elliptical region. 
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Parameters 


Return Value | 


Comments 


Example 


See Also 


[prc | 
Points to a RECT structure that contains the logical coordinates of the upper- 
left and lower-right corners of the bounding rectangle of the ellipse. The RECT 
structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top;. 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the handle of the region if the function is successful. Other- 
wise, itis NULL. 


The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When it has finished using a region created by CreateEllipticRgnIndirect, an ap- 
plication should remove the region by using the DeleteObject function. 


The following example assigns values to the members of a RECT structure, uses 
the CreateEllipticRgnIndirect function to create an elliptical region, selects the 
region into a device context, and then uses the PaintRgn function to display the re- 
gion: 


HDC hdc; 
RECT rc; 
HRGN hrgn; 


SetRect(&rc, 10, 10, 200, 9@); 
hrgn = CreateEllipticRgnIndirect(&rc); 


SelectObject(hdc, hrgn); 
PaintRgn(hdc, hrgn); 


CreateEllipticRgn, DeleteObject, PaintRgn 
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CreateFont Ey 


HFONT CreateFont(nHeight, nWidth, nEscapement, nOrientation, fnWeight, fbitalic, fbUnderline, 
foStrikeOut, foCharSet, foOutputPrecision, fbClipPrecision, carr ate eae ipszFace) 


int nHeight; /* font height 

int nWidth; /* character width y 
int nEscapement; /* escapement of line of text } 
int nOrientation; _ /* angle of base line and x-axis st 
int fnWeight; /* font weight **/ 
BYTE fbltalic; | /* flag for italic attribute sa | 
BYTE fbUnderline; /* flag for underline attribute */ 
BYTE /fbStrikeOut; /* flag for strikeout attribute we 
BYTE fbCharSet; /* character set **/ 
BYTE fbOutputPrecision; /* output precision | */ 
BYTE /fbClipPrecision; /* clipping precision 7] 
BYTE fbQuality; /* output quality */ 
BYTE fbPitchAndFamily; —_/* pitch and family =) 
LPCSTR IpszFace; /* address of typeface name */ 


The CreateF ont function creates a logical font that has the specified charac- | 
teristics. The logical font can subsequently be selected as the font for any device. | 


- Parameters | nHeight 

| Specifies the requested height, in logical units, for the font. If this parameter is 
greater than zero, it specifies the cell height of the font. If it is less than zero, it 
specifies the character height of the font. (Character height is the cell height _ 
minus the internal leading. Applications that specify font height in points typi- 
cally use a negative number for this member.) If this parameter is zero, the font 
mapper uses a default height. The font mapper chooses the largest physical font 
that does not exceed the requested size (or the smallest font, if all the fonts | 
exceed the requested size). The absolute value of the nHeight parameter must 
not exceed 16,384 after it is converted to device units. 


nWidth | 

Specifies the average width, in logical units, of characters in the font. If this pa- 
rameter is zero, the font mapper chooses a “closest match” default width for the 
specified font height. (The default width is chosen by matching the aspect ratio: 
of the device against the digitization aspect ratio of the available fonts. The 
closest match is determined by the absolute value of the difference. ) 


nEscapement | 
Specifies the angle, in tenths of degrees, between the escapement vector and the 
_ x-axis of the screen surface. The escapement vector is the line through the | 
origins of the first and last characters on a line. The angle is measured counter- 
clockwise from the x-axis. | 
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nOrientation 
Specifies the angle, in tenths of degrees, between the base line of a character 
and the x-axis. The angle is measured in a counterclockwise direction from the 
x-axis for left-handed coordinate systems (that is, MM_TEXT, in which the 
y-direction is down) and in a clockwise direction from the x-axis for right- 
handed coordinate systems (in which the y-direction is up). © 


| fnWeight 7 
Specifies the font weight. This parameter can be one of the following values: 


Constant Value 
FW_DONTCARE 0 
FW_THIN 100 


FW_EXTRALIGHT 200 
FW_ULTRALIGHT 200 


FW_LIGHT 300 
FW_NORMAL  — 400 
FW_REGULAR 400 
FW_MEDIUM 500 
FW_SEMIBOLD — 600 
FW_DEMIBOLD _ 600 
FW_BOLD 700 


FW_EXTRABOLD 800 
FW_ULTRABOLD 800 
FW_BLACK 900 
FW_HEAVY 900 


The appearance of the font depends on the typeface. Some fonts have 
only FW_NORMAL, FW_REGULAR, and FW_BOLD weights. If 
FW_DONTCARE is specified, a default weight is used. 


foltalic 
Specifies an italic font if set to nonzero. 


_fbUnderline 
Specifies an underlined font if set to nonzero. 


fbStrikeOut | 
Specifies a strikeout font if set to nonzero. 


fbCharSet | | 
Specifies the character set of the font. The following values are predefined: 
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Constant Value 


ANSI_CHARSET 0 
DEFAULT_CHARSET I 
SYMBOL_CHARSET Z 
SHIFTJIS_CHARSET 128 
OEM_CHARSET 255 


The DEFAULT_CHARSET value is not used by the font mapper. An applica- 
tion can use this value to allow the name and size of a font to fully describe the 
logical font. If the specified font name does not exist, a font from any character 
set can be substituted for the specified font; to avoid unexpected results, applica- 
tions should use the DEFAULT_CHARSET value sparingly. 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. If an application uses a 
font with an unknown character set, it should not attempt to translate or inter- 
pret strings that are to be rendered with that font. © 


foOutputPrecision 
Specifies the requested output precision. The output precision defines how 
closely the output must match the requested font’s height, width, character 
orientation, escapement, and pitch. This parameter can be one of the following 
values: 


OUT_CHARACTER_PRECIS 
OUT_DEFAULT_PRECIS 
OUT_DEVICE_PRECIS 
OUT_RASTER_PRECIS 
OUT_STRING_PRECIS 
OUT_STROKE_PRECIS 
OUT_TT_PRECIS 


Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, 
and OUT_TT_PRECIS values to control how the font mapper chooses a font 
when the system contains more than one font with a given name. For example, 
_ if a system contained a font named Symbol in raster and TrueType form, speci- 
— fying OUT_TT_PRECIS would force the font mapper to choose the TrueType 
version. (Specifying OUT_TT_PRECIS forces the font mapper to choose a 
TrueType font whenever the specified font name matches a device or raster 
font, even when there is no TrueType font of the same name.) 


fbClipPrecision | 
_ Specifies the requested clipping precision. The clipping precision defines how 
to clip characters that are partially outside the clpping Feeley: This parameter - 
can be one of the following values: 


~CLIP_CHARACTER PRECIS 
-CLIP_DEFAULT_PRECIS 
CLIP_LENCAPSULATE _ 
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CLIP_LH_ANGLES 
CLIP_MASK 
CLIP_STROKE_PRECIS 
CLIP_TT_ALWAYS 


To use an embedded read-only font, applications must specify | 
CLIP_ENCAPSULATE. 


To achieve consistent rotation of device, TrueType, and vector fonts, an applica- 
tion can use the OR operator to combine the CLIP_LH_ANGLES value with 
any of the other fbClipPrecision values. If the CLIP_LH_ANGLES bit is set, 
the rotation for all fonts is dependent on whether the orientation of the coordi- 
nate system is left-handed or right-handed. If CLIP_LH_ANGLES is not set, _ 
device fonts always rotate counterclockwise, but the rotation of other fonts is 
dependent on the orientation of the coordinate system. (For more information 
about the orientation of coordinate systems, see the description of the 
nOrientation parameter.) 


fbQuality | 


Specifies the output quality of the font, which defines how carefully the 
graphics device interface (GDI) must attempt to match the attributes of a logical 
font to those of a physical font. This parameter can be one of the following 
values: | 


Value Meaning 
DEFAULT QUALITY Appearance of the font does not matter. 


DRAFT_QUALITY Appearance of the font is less important than when the 


PROOF_QUALITY value is used. For GDI raster fonts, 
scaling is enabled. Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 


PROOF_QUALITY Character quality of the font is more important than 
exact matching of the logical-font attributes. For GDI 
raster fonts, scaling is disabled and the font closest in 
size is chosen. Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 


fbPitchAndFamily 


Specifies the pitch and family of the font. The two low-order bits specify the 
pitch of the font and can be one of the following values: 


DEFAULT_PITCH 


FIXED_PITCH 
VARIABLE _ PITCH 


Applications can set bit 2 (0x04) of the IfPitchAndFamily member to choose a 
TrueType font. 


The four high-order bits specify the font family and can be one of the following 
values: | | 


Return Value 


Comments 


Example 
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Value | Meaning 

FF_DECORATIVE Novelty fonts. Old English is an example. 

FF_DONTCARE Don’t care or don’t know. 

FF_MODERN Fonts with constant stroke width, with or without serifs. 

| Pica, Elite, and Courier New® are examples. | 

FF_ROMAN Fonts with variable stroke width and with serifs. Times 
New Roman® and New ee Schoolbook® are ex- 
amples. 

FF_SCRIPT Fonts designed to look like handwriting. Script and Cursive 
are examples. 

FF_SWISS Fonts with variable stroke width and without serifs. MS® 


Sans Serif is an example. 


An application can specify a value for the fbPitchAndFamily parameter by 
using the Boolean OR operator to join a pitch constant with a family constant. _ 


Font families describe the look of a font in a general way. They are intended for 
specifying fonts when the exact typeface requested is not available. 


lpszFace 
Points to a null-terminated string that specifies the typeface name of th the font. 
The length of this string must not exceed LF_FACESIZE — 1. The EnumFont- 
Families function can be used to enumerate the typeface names of all currently 
available fonts. If this assraatatl is NULL, GDI uses a device- pis eee type- 
face. | 


The return value is the handle of the logical font if the function is successful. 
Otherwise, itis NULL. 


The CreateFont function creates the handle of a logical font. The font mapper 
uses this logical font to find the closest match from the fonts available in GDI’s 


pool of physical fonts. 


Applications can use the default settings for most of these parameters when creat- 
ing a logical font. The parameters that should always be given specific values are 
nHeight and IpszFace. If nHeight and lpszFace are not set by the application, the 

logical font that is created is device-dependent. | 


Fonts created by using the CreateFont function must be selected out of any 


device context in which they were used and then removed by usIng the Delete- 
Object function. : ae 


The foliowitie example sets the mapping mode to MM_TWIPS and then uses the 
CreateFont function to create an 18- “point logical font: 
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HFONT hfont, hfontOld; 
int MapModePrevious, iPtSize = 18; 
PSTR pszFace = "MS Serif"; 


MapModePrevious = SetMapMode(hdc, MM_TWIPS); 
hfont = CreateFont(-iPtSize * 20, 0, @, @, @, /* specify pt size * / 
0, 0, 0, 0, 0, @, 0, 0, pszFace); /* and face name only */ 


hfontOld = SelectObject(hdc, hfont); 
TextOut(hdc, 100, -500, pszFace, strlen(pszFace)); 


SetMapMode(hdc, MapModePrevious); 
SelectObject(hdc, hfont0Old); 


DeleteObject(hfont) ; 
See Also CreateFontIndirect, DeleteObject, EnumFontFamilies 
CreateFontindirect [2x | 


HFONT CreateFontIndirect(/p//) 
const LOGFONT FAR? Ipi/f; 


/* address of struct. with font attributes **/ 


The CreateFontIndirect function creates a logical font that has the characteristics 
given in the specified structure. The font can subsequently be selected as the cur- 
rent font for any device. 


Parameters Iplf 


Points to a LOGFONT structure that defines the characteristics of the logical 
font. The LOGFONT structure has the following form: 


typedef struct tagLOGFONT { 


int 
int 
int 
int 
int 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
} LOGFONT; 


/* |f */ 
lfHeight; 

1fWidth; 

1fEscapement; 
1fOrientation; 

1fWeight; 

lfItalic; 

1fUnderline; 
1fStrikeOut; 

1fCharSet; 
1fOutPrecision; 
1fClipPrecision; 
1fQuality; 
1fPitchAndFamily; 
1fFaceName[LF_FACESIZE]; 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is the handle of the logical font if the function is successful. 


Otherwise, it is NULL. 
Comments The CreateFontIndirect function creates a logical font that has the characteristics 


specified in the LOGFONT structure. When the font is selected by using the 
SelectObject function, the graphics device interface (GDI) font mapper attempts 
to match the logical font with an existing physical font. If it cannot find an exact 
match for the logical font, the font mapper provides an alternative whose charac- 
teristics match as many of the requested characteristics as possible. 


Fonts created by using the CreateFontIndirect function must be selected out of 
any device context in which they were used and then removed by using the 
DeleteObject function. | 


Example — The following example uses the CreateFontIndirect function to retrieve the 
handle of a logical font. The nPtSize and pszFace parameters are passed to the 
function containing this code. The MulDiv and GetDeviceCaps functions are 
used to convert the specified point size into the correct point size for the 
MM_TEXT mapping mode on the current device. 


HFONT hfont, hfontOld; 
PLOGFONT plf = (PLOGFONT) LocalAlloc(LPTR, sizeof(LOGFONT)); 


plf->1fHeight = -MulDiv(nPtSize, GetDeviceCaps(hdc, LOGPIXELSY), 72); 
strcpy(plf->1fFaceName, pszFace); | 


hfont = CreateFontIndirect(p1f); 
hfontOld = SelectObject(hdc, hfont); 
TextOut(hdc, 10, 50, pszFace, strlen(pszFace)); 
Local Free((HLOCAL) plf); 


SelectObject(hdc, hfont0ld); 
DeleteObject(hfont); 


See Also oe | CreateF ont, DeleteObject 
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CreateHatchBrush 7 i 


HBRUSH CreateHatchBrush(fnStyle, clrref) 
int fnStyle; /* hatch style of brush if 
COLORREF clrref; /* color of brush */ 


The CreateHatchBrush function creates a brush that has the specified hatched 
pattern and color. The brush can then be selected for any device. 


Parameters jnStyle 
Specifies one of the following hatch styles for the brush: 
Value Meaning 
HS_BDIAGONAL 45-degree upward hatch (left to right) 
HS_CROSS Horizontal and vertical crosshatch 


HS_DIAGCROSS 45-degree crosshatch 
HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS_HORIZONTAL Horizontal hatch 

HS_VERTICAL Vertical hatch 


clrref 
Specifies the foreground color of the brush (the color of the hatches). 


Return Value The return value is the handle of the brush if the function is successful. Otherwise, 
itis NULL. | 
Comments When an application has finished using the brush created by the CreateHatch- 


Brush function, it should select the brush out of the device context and then delete 
it by using the DeleteObject function. 


The following illustration shows how the various hatch brushes appear when used 
to fill a rectangle: 


HS_HORIZONTAL HS_BDIAGONAL HS_FDIAGONAL 


BO 


HS_VERTICAL | HS_CROSS 


Ll cae : i 
XX XX £\ 


Example 


See Also 


CreatelC 
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The following example creates a hatched brush with green diagonal hatch marks 
and uses that brush to fill a rectangle: 


HBRUSH hbr, hbrOld; 


hbr = CreateHatchBrush(HS FDIAGONAL, RGB(@, 255, @)); 
hbrOld = SelectObject(hdc, hbr); 
Rectangle(hdc, 0, 0, 100, 100); 


CreateBrushIndirect, CreateDIBPatternBrush, CreatePatternBrush, 
CreateSolidBrush, DeleteObject, SelectObject 


HDC CreateIC(/pszDriver, IpszDevice, lpszOutput, lpvInitData) 


LPCSTR [pszDriver; /* address of driver name **/ 
LPCSTR I[pszDevice; /* address of device name sa 
LPCSTR IpszOutput;_. /* address of filename or port name st 
const void FAR®* [pvInitData; /* address of initialization data wi 


Parameters 


The CreateIC function creates an information context for the specified device. 
The information context provides a fast way to get information about the device 
without creating a device context. 


[pszDriver 
Points to a null-terminated string that specifies the MS-DOS filename (without 
extension) of the device driver (for example, EPSON). 


[pszDevice 
Points to a null-terminated string that specifies the name of the specific device 
to be supported (for example, EPSON FX-80). This ao is used if the 
module supports more than one device. 


IpszOutput 
Points to a null-terminated string that specifies the MS-DOS filename or device 
name for the physical output medium (file or port). 


lpvInitData 
Points to a DEVMODE structure that contains, initially, device-specific infor- 
mation necessary to initialize the device driver. The ExtDeviceMode function 
retrieves this structure filled in for a given device. The /pvInitData parameter 
must be NULL if the device driver is to use the default initialization informa- 
tion (if any) specified by the user through Windows Control Panel. 
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Return Value 


Comments 


Example 


The DEVMODE structure has the following form: 


#include <print. h> 


typedef struct tagDEVMODE { /* dm */ 
char dmDeviceName[CCHDEVICENAME]; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDriverExtra; 
DWORD dmFields; 
int dmOrientation; 
int dmPaperSize; 
int dmPaperLength; 
int dmPaperWidth; 
int dmScale; 
int dmCopies; 
int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; 
int dmDuplex; 
int dmYResolution; 
int dmTTOption; 
} DEVMODE; 


The return value is the handle of an information context for the given device if the 
function is successful. Otherwise, it is NULL. 


The PRINT.H header file is required if the DEVMODE structure is used. 


MS-DOS device names follow MS-DOS conventions; an ending colon (:) is rec- 
ommended, but optional. Windows strips the terminating colon so that a device 
name ending with a colon is mapped to the same port as would be the same name 
without a colon. 


The driver and port names must not contain leading or trailing spaces. 
GDI output functions cannot be used with information contexts. 


When it has finished using an information context created by CreateIC, an appli- 
cation should remove the information context by using the DeleteDC function. 


The following example uses the CreateIC function to create an information con- 
text for the display and then uses the ae function to retrieve the origin for 


the information context: 


HDC hdclC; 
DWORD dwOrigin; 
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hdcIC = CreateIC("DISPLAY", NULL, NULL, NULL); 
dwOrigin = GetDCOrg(hdcIC); 


DeleteDC(hdcIC); 


See Also — CreateDC, DeleteDC, ExtDeviceMode 
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HICON Createlcon(hinst, nWidth, nHeight, bPlanes, bBitsPixel, IpvANDbits, IpvXORbits) 
ia 


HINSTANCE hinst; /* handle of application instance 

int nWidth; | /* icon width sf | 
int nHeight; /* icon height ef 
BYTE bPlanes; /* number of planes in XOR mask ey 
BYTE DBitsPixel; /* number of bits per pixel in XOR mask a 
const void FAR* [pvANDbits; /* address of AND mask array *) 
const void FAR* ipvXORbits; /* address of XOR mask array Se, oy 


The CreateIcon function creates an icon that has the specified width, height, 
colors, and bit patterns. 


Parameters hinst 

Identifies an instance of the module that will create the icon. 
nWidth 

Specifies the width, in pixels, of the icon. 
nH. eight 

Specifies the height, in pixels, of the icon. 
bPlanes 

Specifies the number of planes in the XOR mask of the icon. 
bBitsPixel 

Specifies the number of bits per pixel in the XOR mask of the icon. 
lpvANDbits 


Points to an array of bytes that contains the bit values for the AND mask of the 
icon. This array must specify a monochrome mask. 


lpvXORbits 
Points to an array of bytes that contains the bit values for the XOR mask of the 
icon. These bits can be the bits of a monochrome or device-dependent color bit- 
map. : 


Return Value The return value is the handle of the icon if oe function is successful. Otherwise, 
itis NULL. 
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Comments 


See Also 


CreateMenu 


The nWidth and nHeight parameters must specify a width and height supported by 
the current display driver, since the system cannot create icons of other sizes. An 
application can determine the width and height supported by the display driver by 
calling the GetSystemMetrics function, specifying the SM_CXICON or 
SM_CYICON constant. | 


Before terminating, an application must call the DestroyIcon function to free Sys- 
tem resources associated with the icon. 


DestroyIcon, GetSystemMetrics 


[2x] 


HMENU CreateMenu(void) 


Parameters 


Return Value 


Comments 


Example 


The CreateMenu function creates a menu. The menu is initially empty but can be 
filled with menu items by using the AppendMenu or InsertMenu function. 


This function has no parameters. 


The return value is the handle of the newly created menu if the function is success- 
ful. Otherwise, it is NULL. 


If the menu is not assigned to a window, an application must free system resources 
associated with the menu before exiting. An application frees menu resources by 
calling the DestroyMenu function. Windows automatically frees resources as- 
sociated with a menu that is assigned to a window. 


The following example creates a main menu and a pop-up menu and associates the 
pop-up menu with an item in the main menu: 


HMENU hmenu; 
HMENU hmenuPopup; 


/* Create the main and pop-up menu handles. */ 


hmenu = CreateMenu(); 
hmenuPopup = CreatePopupMenu();_ 


See Also 


CreateMetaFile 
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/* Create the pop-up menu items. *./ 


AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_NEW, 


"&New™); | 
AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_SAVE, 
"&Save"); 
AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_SAVE_AS, 
"&Save As"); 


/* Add the pop-up menu to the main menu. */ 


AppendMenu(hmenu, MF_ENABLED | MF_POPUP, (UINT) hmenuPopup, 
"&File"); | 


AppendMenu, DestroyMenu, InsertMenu, SetMenu 


HDC CreateMetaFile(/pszFile) 


LPCSTR IpszFile; 


Parameters 


Return Value 
Comments 


Example 


/* address of metafile name **/ 


The CreateMetaFile function creates a metafile device context. 


lpszFile | : | 
Points to a null-terminated string that specifies the MS-DOS filename of the 
metafile to create. If this parameter is NULL, a device context for a memory 
metafile is returned. 


The return value is the handle of the metafile device context if the function is 
successful. Otherwise, itis NULL. | 


When it has finished using a metafile device context created by CreateMetaFile, 
an application should close it by using the CloseMetaFile function. 


The following example uses the CreateMetaFile function to create the handle of a 


device context for a memory metafile, draws a line in that device context, retrieves 
a handle of the metafile by calling the CloseMetaFile function, plays the metafile — 
by using the PlayMetaFile function, and finally deletes the metafile by using the 
DeleteMetaFile function: 


HDC hdcMeta; 
HMETAFILE hmf; 
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hdcMeta = CreateMetaFile(NULL); 
MovelTo(hdcMeta, 10, 10); 
LineTo(hdcMeta, 100, 100); 

hmf = CloseMetaFile(hdcMeta); 
PlayMetaFile(hdc, hmf); 


DeleteMetaFile(hmf); 
See Also DeleteMetaFile 
CreatePalette 


HPALETTE CreatePalette(/p/gpl) 


const LOGPALETTE FAR* [plgpi; 


Parameters 


Return Value 


Comments 


Example 


The CreatePalette function creates a logical color palette. 


[pl gpl 


/* address of LOGPALETTE structure 


Points to a LOGPALETTE structure that contains information about the 
colors in the logical palette. The LOGPALETTE structure has the following 


form: 


typedef struct tagLOGPALETTE { /* lgpl */ 


WORD palVersion; 


WORD palNumEntries; 
PALETTEENTRY palPalEntry[1]; 


} LOGPALETTE; 


For a full description of this structure, see the Microsoft Windows Program- 


mer’s Reference, Volume 3. 


The return value is the handle of the logical palette if the function is successful. | 


Otherwise, itis NULL. 


When it has finished using a palette created by CreatePalette, an application 


should remove the palette by using the DeleteObject function. 


The following example initializes a LOGPALETTE structure and an array of 
PALETTEENTRY structures, and then uses the CreatePalette function to re- 


trieve a handle of a logical palette: 


#tdefine NUMENTRIES 128 
HPALETTE hpal; — 
PALETTEENTRY ape[LNUMENTRIES]; 


CreatePatternBrush 


plgpl = (LOGPALETTE*) LocalAlloc(LPTR, 
sizeof(LOGPALETTE) + cColors * sizeof(PALETTEENTRY)); 


plgpl->palNumEntries = cColors; 
plgpl->palVersion = Qx30Q; 


for (i = @, red = @, green = 127, blue = 127; i < NUMENTRIES; 
i++, red += 1, green t= 1, blue t= 1) { 
apeLi].peRed = 
plgpl->palPalEntry[i].peRed = LOBYTE(red); 
apeLi].peGreen = 
plgpl->palPalEntry[i].peGreen = LOBYTE(green); 
apeLi].peBlue = 
plgpl->palPalEntry[i].peBlue = LOBYTE(blue); 
apeLi].peFlags = 
plgpl->palPalEntry[Li].peFlags = PC_RESERVED; 
} 
hpal = CreatePalette(plgpl); 
LocalFree((HLOCAL) plgpl); 


. /* Use the palette handle. */ 


DeleteObject(hpal); 
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[2x] 


See Also DeleteObject 

CreatePatternBrush 

HBRUSH CreatePatternBrush(hbmp) 

HBITMAP hbmp; /* handle of bitmap i | 
The CreatePatternBrush function creates a brush whose pattern is specified by a 
bitmap. The brush can subsequently be selected for any device that supports raster 
operations. 

Parameters hbmp 

Identifies the bitmap. 

Return Value : The return value is the handle of the brush if the function is successful. Otherwise. 
itis NULL. 
The bitmap identified by the hbmp parameter is typically created by using the 


Comments 


Bitmap function. 


_CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, or Load- 
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Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, © 
Windows will use the bits corresponding to only the first 8 rows and 8 columns of 
pixels in the upper-left corner of the bitmap. 


An application can use the DeleteObject function to remove a pattern brush. This 
does not affect the associated bitmap, which means the bitmap can be used to cre- 
ate any number of pattern brushes. In any case, when the brush is no longer 
needed, the application should remove it by using DeleteObject. 


A brush created by using a monochrome bitmap (one color plane, one bit per 
pixel) is drawn using the current text and background colors. Pixels represented by 
a bit set to 0 are drawn with the current text color, and pixels represented by a bit 
set to 1 are drawn with the current background color. 


Example The following example loads a bitmap named Pattern, uses the bitmap to create a 
7 pattern brush in a call to the CreatePatternBrush function, selects the brush into 
a device context, and fills a rectangle by using the new brush: — 


HBITMAP hbmp; 
HBRUSH hbr, hbrOld; 


hbmp = LoadBitmap(hinst, "Pattern"); 
hbr = CreatePatternBrush(hbmp) ; 
hbrOld = SelectObject(hdc, hbr); 
Rectangle(hdc, 10, 10, 100, 100); 


See Also CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIB- 
PatternBrush, DeleteObject, GetDeviceCaps, LoadBitmap, SelectObject, 
SetBkColor, SetTextColor 


CreatePen nee [2x | 
HPEN CreatePen(fnPenStyle, nWidth, clrref) 
int fnPenStyle; /* style of pen i 


int nWidth; /* width of pen a 
COLORREF clrref; /* color of pen =] 


_ The CreatePen function creates a pen having the specified style, width, and color. | 
The pen can subsequently be selected as the current pen for any device. 


Parameters : 


Return Value 


Comments 
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_jnPenStyle 
Specifies the pen style. This parameter can be one of the following values: 
Value Meaning 
PS_SOLID _ Creates a solid pen. 
PS_DASH | Creates a dashed pen. (Valid only when the pen width is 1.) 
PS_DOT Creates a dotted pen. (Valid only when the pen width is 1.) 
PS_DASHDOT Creates a pen with alternating dashes and dots. (Valid only 


when the pen width is 1.) 


PS_DASHDOTDOT Creates a pen with alternating dashes and double dots. 
(Valid only when the pen width is 1.) 

PS_NULL Creates a null pen. 

PS_INSIDEFRAME Creates a pen that draws a line inside the frame of closed 

| shapes produced by graphics device interface (GDI) out- | 

put functions that specify a bounding rectangle (for ex- 
ample, the Ellipse, Rectangle, RoundRect, Pie, and _ 
Chord functions). When this style is used with GDI out- 
put functions that do not specify a bounding rectangle (for 
example, the LineTo function), the drawing area of the 
pen is not limited by a frame. © 


nWidth | | 
_ Specifies the width, in logical units, of the pen. If this value is zero, the width in 
device units is always one pixel, regardless of the mapping mode. 


clrref | 
Specifies the color of the pen. 


The return value is the handle of the pen if the function is successful. Oiticrwise, it 
is NULL. ! | 


Pens whose width is greater than one pixel always have the PS. _NULL, 
PS_SOLID, or PS_INSIDEFRAME style. 


If a pen has the PS_INSIDEFRAME style and a color that does not match a color | 


in the logical color table, the pen is drawn with a dithered color. The PS -SOLID o 
pen style cannot be used to create a pen with a dithered color. The | 


~PS_INSIDEFRAME la 1S identical to PS _SOLID if the pen width is less than | 


or equal to 1. 


- When it has finished using a pen created by CreatePen, an application shouldt re- 
move the pen by using the DeleteObject function. | : 
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The following illustration shows how the various system pens appear when used 
to draw a rectangle. 


PS_SOLID 


PS_DASH 


PS_DOT 


' PS DASHDOT 


' PS_DASHDOTDOT 


Example The following example uses the CreatePen function to create a solid blue pen 6 
units wide, selects the pen into a device context, and then uses the pen to draw a 
rectangle: 


HPEN hpen, hpenOld; 


hpen = CreatePen(PS_SOLID, 6, RGB(@, @, 255)); 
hpenOld = SelectObject(hdc, hpen); 


Rectangle(hdc, 10, 10, 100, 100); 


SelectObject(hdc, hpen0ld); 
DeleteObject(hpen) ; 


See Also | CreatePenIndirect, DeleteObject, Ellipse, Rectangle, RoundRect 


CreatePenindirect 2x | 


HPEN CreatePenIndirect(/plgpn) 
LOGPEN FAR* Iplgpn; /* address of structure with pen data sl 


The CreatePenIndirect function creates a pen that has the style, width, and color 
given in the specified structure. 


Parameters Iplgpn 7 | 
Points to the LOGPEN structure that contains information about the pen. The 
LOGPEN structure has the following form: 
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typedef struct tagLOGPEN { /* lIgpn */ 
UINT lopnStyle; 
POINT lopnWidth; 
COLORREF lopnColor; 

} LOGPEN; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is the handle of the pen if the function is successful. Otherwise, it 
a is NULL. | 
Comments Pens whose width is greater than 1 pixel always have the PS_NULL, PS_SOLID, 


or PS_INSIDEFRAME style. 


Ifa pen has the PS_INSIDEFRAME style and a color that does not match a color 
— in the logical color table, the pen is drawn with a dithered color. The 
PS_INSIDEFRAME style is identical to PS_SOLID if the pen width is less than 
or equal to 1. 


When it has finished using a pen created by CreatePenIndirect, an application 
should remove the pen by using the DeleteObject function. 


Example The following example fills a LOGPEN structure with values defining a solid red 
pen 10 logical units wide, uses the CreatePenIndirect function to create this pen, 
selects the pen into a device context, and then uses the pen to draw a rectangle: 


LOGPEN 1p; | 
HPEN hpen, hpenOld; 


PS_SOLID; 

= 10; 

= 0; _ /* y-dimension not used */ 
RGB(255, @, @); : 


lp.lopnStyle 
Ip.lopnWidth. 
lp. lopnWidth. 
lp.lopnColor 


<< * I 


hpen = CreatePenIndirect(&lp); 
~hpenOld = SelectObject(hdc, hpen); 
Rectangle(hdc, 10, 10, 100, 100); 


See Also CreatePen, DeleteObject — 
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CreatePolygonRgn 


HRGN CreatePolygonRegen(/ppt, cPoints, fnPolyFillMode) 


int cPoints; 
int fnPolyFillMode; 


const POINT FAR* [ppt; /* address of array of points */ 
/* number of points in array */ 
/* polygon-filling mode a 


Parameters 


Return Value 


Comments 


The CreatePolygonRgn function creates a polygonal region. The system closes 
the polygon automatically, if necessary, by drawing a line from the last vertex to 
the first. 


ppt 


Points to an array of POINT structures. Each structure specifies the eecede 
nate and y-coordinate of one vertex of the polygon. The POINT structure has 
the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the M. TOS} Windows Program- 
mer’s Reference, Volume 3. 


cPoints 
Specifies the number of POINT structures in the array pointed to by the /ppt pa- 
rameter. 


jnPolyF illMode , 
Specifies the polygon-filling mode. This value may be either ALTERNATE or 
WINDING. 


The return value is the handle of the region if the function is successful. Other- 
wise, itis NULL. 


The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, the system increments a count (increases 


Example 


See Also 
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it by one); when the line passes through a counterclockwise line segment, the sys- 
tem decrements the count. The area is filled if the count is nonzero when the line 
reaches the outside of the figure. 


When it has finished using a region created by CreatePolygonRgn, an application 
should remove the region by using the DeleteObject function. 


The following example fills an array of POINT structures with the coordinates of 
a five-pointed star, uses this array in a call to the CreatePolygonRgn function, 
selects the region into a device context, and then uses the PaintRgn function to 
display the region: 


HDC hdc; 
HRGN hrgn; 
POINT apts[5] = {{ 200, 10 }, 
{ 300, 200 }, 
{ 100, 100 }, 
{ 300, 100 }, 
{ 100, 200 }}; 
hrgn = CreatePolygonRgn(apts, /* array of points */ 
sizeof(apts) / sizeof(POINT), /* number of points */ 
ALTERNATE); | /* alternate mode */ 


SelectObject(hdc, hrgn); 
PaintRgn(hdc, hrgn); 


CreatePolyPolygonRgn, DeleteObject, Polygon, SetPolyFillMode 


CreatePolyPolygonRgn : 


-HRGN CreatePolyPolygonRen(ippt, IpnPolyCount, cIntegers, fnPolyF warn 


const POINT FAR®* Ippt; /* address of structure of points | a ae 
const int FAR* /pnPolyCount; /* address of array of vertex data =) 
‘int cIntegers; /* number of integers in array wel SY. 
int fnPolyF illMode; /* polygon-filling mode eo 18 | 
The CreatePolyPolygonRen function creates a region consisting of a series of 
aosed polygons. The polygons may be disjoint, or they may overlap. 
Parameters [ppt 


Points to an array of POIN T structures that define the vertices of the polygons. 
Each polygon must be explicitly closed, because the system does not close 
them automatically. The polygons are specified pons AE: The oles 
structure has the following form: 
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Return Value 


Comments 


Example 


typedef struct tagPOINT { /* pt */ 
int x; | 
int y; 
- } POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


[pnPolyCount 
Points to an array of integers. The first integer specifies the number of vertices 
in the first polygon in the array pointed to by the /ppt parameter, the second in- 
teger specifies the number of vertices in the second polygon, and so on. 


clntegers 
Specifies the total number of integers in the array pointed to by the IpnPoly- 
Count parameter. 


jnPolyFillMode 
Specifies the polygon-filling mode. This value may be either ALTERNATE or 
WINDING. 


The return value is the handle of the region if the function is successful. Other- 
wise, itis NULL. 


The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, the system increments a count (increases 
it by one); when the line passes through a counterclockwise line segment, the sys- 
tem decrements the count. The area is filled if the count is nonzero when the line 
reaches the outside of the figure. 


When it has finished using a region created by CreatePolyPolygonRgn, an appli- 
cation should remove the region by using the DeleteObject function. 


The following example fills an array of POINT structures with the coordinates of 
a five-pointed star and a rectangle, uses this array in a call to the CreatePoly- 
PolygonRgn function, selects the region into a device context, and then uses the 
PaintRgn function to display the region: 


See Also 


CreatePopupMenu 121 


HDC hdc; 

HRGN hrgn; 

int aVertices[2] 
POINT apts[11] = 


{ 6, 5 }; 


{{ 200, 10 


{ ie 

{ 300, 200 }, | 

{ 100, 100 }, /* Star figure, manually closed */ 

{ 300, 100 }, 

{ 100, 200 }, 

{ 200, 10 }, 

{ 10, 150 }, 

{ 350, 150 }, 

{ 350, 170 }, /* Rectangle, manually closed */ 

{ 10, 170 }, 

{ 10, 150 }}; 

hrgn = CreatePolyPolygonRgn(apts, /* array of points x / 

aVertices, /* array of vertices * / 
sizeof(aVertices) / sizeof(int), /* integers in vertex array */ 
ALTERNATE); /* alternate mode * / 


~ SelectObject(hdc, hrgn); 


PaintRgn(hdc, hrgn); 


CreatePolygonRgn, DeleteObject, PolyPolygon, SetPolyFillMode 
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HMENU CreatePopupMenu(void) 


Parameters 


Return Value 


Comments 


The CreatePopupMenu function creates an empty pop-up menu. 


This function has no parameters. 


The return value is the handle of the newly created menu if the function iS SUCCeSS- 
ful. Otherwise, it is NULL. 


An application adds items to the pop-up menu by calling the InsertMenu and 
AppendMenu functions. The application can add the pop-up menu to an existing 
menu or pop-up menu, or it can display and track selections on the pop-up menu 
by calling the TrackPopupMenu function. 


Before exiting, an application must free system resources associated with a pop-up 


menu if the menu is not assigned to a window. An application frees a menu by 
calling the DestroyMenu function. 
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Example The following example creates a main menu and a pop-up menu, and associates 
the pop-up menu with an item in the main menu: 


HMENU hmenu; 
HMENU hmenuPopup; 


/* Create the main and pop-up menu handles. */ 


hmenu = CreateMenu(); 
hmenuPopup = CreatePopupMenu( ); 


/* Create the pop-up menu items. *./ 


AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_NEW, 


"&New"); 

AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_SAVE, 
"&Save"); 

AppendMenu(hmenuPopup, MF_ENABLED | MF_STRING, IDM_SAVE_AS, 
"&Save As"); 


/* Add the pop-up menu to the main menu. */ 


AppendMenu(hmenu, MF_ENABLED | MF_POPUP, (UINT) hmenuPopup, 
"&File"); | 


See Also | AppendMenu, CreateMenu, InsertMenu, SetMenu, TrackPopupMenu 


CreateRectRgn 7 [2x | 


HRGN CreateRectRgn(nLeftRect, nTopRect, nRightRect, nBottomRect) 


int nLeftRect; /* x-coordinate upper-left corner of region | 
int nTopRect; /* y-coordinate upper-left corner of region Hse 
int nRightRect; /* x-coordinate lower-right corner of region a 
int nBottomRect; /* y-coordinate lower-right corner of region a 


The CreateRectRgn function creates a rectangular region. 


Parameters nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the region. 


nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the region. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the region. 
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nBottomRect | 
Specifies the logical y- eeauiainale of the lower-right corner of the region. 


Return Value The return value is the handle of a rectangular region if the function is successful. 
Otherwise, it is NULL. 


Comments The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When it has finished using a region created by CreateRectRgn, an application 
should remove the region by using the DeleteObject function. 


Example The following example uses the CreateRectRgn function to create a rectangular 
region, selects the region into a device context, and then uses the PaintRgn func- 
tion to display the region: 


HDC hdc; 
HRGN hrgn; 


hrgn = CreateRectRgn(10, 10, 110, 110); 
SelectObject(hdc, hrgn); 
PaintRgn(hdc, hrgn);. 


See Also CreateRectRgnIndirect, CreateRoundRectRgn, DeleteObject, PaintRgn 


CreateRectRgnindirect — ras] 


HRGN CreateRectRgnIndirect(lprc) 


const RECT FAR® [prc; /* address of structure with region */ 
‘The CreateRectRgnIndirect function creates a rectangular region by using a 
RECT structure. 
Parameters [prc 


‘Points to a RECT structure that contains the logical coordinates of the upper- 
left and lower-right corners of the region. The RECT structure has the follow- 
ing form: 


typedef struct tagRECT { /* ro */ 
int left; | 
int top; 
int right; 
int bottom; 
} RECT; 
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For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is the handle of the rectangular region if the function is success- 
ful. Otherwise, it is NULL. | 


Comments The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. 


When it has finished using a region created by CreateRectRgnIndirect, an appli- 
cation should remove the region by using the DeleteObject function. 


Example The following example assigns values to the members of a RECT structure, uses 
the CreateRectRgnIndirect function to create a rectangular region, selects the re- 
gion into a device context, and then uses the PaintRgn function to display the re- 
gion: 


RECT rc; 
HRGN hrgn; 


SetRect(&rc, 10, 10, 200, 50); 


hrgn = CreateRectRgnIndirect(arc); 
SelectObject(hdc, hrgn); 
PaintRgn(hdc, hrgn); 


See Also | CreateRectRen, CreateRoundRectRgn, DeleteObject, PaintRgn 


CreateRoundRectRgn . | [3.0 | 


HRGN CreateRoundRectRegen(nLeftRect, nTopRect, nRightRect, nBottomRect, nWidthEllipse, 


nHeightEllipse) 
int nLeftRect; /* x-coordinate upper-left corner of region */ 
int nTopRect; /* y-coordinate upper-left corner of region a 
int nRightRect; /* x-coordinate lower-right corner of region **/ 
int nBottomRect; ._ ‘/* y-coordinate lower-right corner of region at] 
int nWidthEllipse; /* height of ellipse for rounded corners sd 
int nHeightEllipse; —_—*/* width of ellipse for rounded corners ef 


The CreateRoundRectRegn function creates a rectangular region with rounded 
corners. 


Parameters 


Return Value 


Comments 


Example 


See Also 


CreateRoundRectRgn 125 


nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the region. 


nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the region. 


nRightRect 
Specifies the logical x-coordinate of the iegenten corner of the region. 


nBottomRect 
Specifies the logical y-coordinate of the lower-right corner “of the region. 


nWidthEllipse 
Specifies the width of the slips’ used to create the rounded corners. 


nHeightEllipse 
Specifies the height of the ellipse used to create the rounded corners. 


The return value i is the handle of the ieev0H if the function i is successful. Other- 
wise, it is NULL. 


The size of a region is limited to 32,767 by 32,767 logical units or 64K of 
memory, whichever is smaller. - 


When it has finished using a region created by CreateRoundRectRegn, an applica- 
tion should remove the region by using the DeleteObject function. 7 


The following example uses the CreateRoundRectRgn function to create a re- 
gion, selects the region into a ae context, and then uses the PaintRgn function | 
to display the region: 


-HRGN hrgn; 


int nEllipWidth = 10; 
int nEllipHeight = 30; 


hrgn = CreateRoundRectRgn(10, 10, 110, 110, 
nEllipWidth, nEllipHeight); 

SelectObject(hdc, hrgn); 

PaintRgn(hdc, hrgn); 


CreateRectRgn, CreateRectRenIndirect, DeleteObject, PaintRgn 
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CreateScalableFontResource [34] 


BOOL CreateScalableFontResource((Hidden, IpszResourceFile, lpszF ontF ile, lpszCurrentPath) 
*/ 


UINT fHidden; /* flag for read-only embedded font 

LPCSTR IpszResourceFile; /* address of filename of font resource **/ 
LPCSTR I[pszFontFile; /* address of filename of scalable font */ 
LPCSTR I[pszCurrentPath; /* address of path to font file */ 


The CreateScalableFontResource function creates a font resource file for the 
specified scalable font file. 


Parameters fHidden 
Specifies whether the font is a read-only embedded font. This parameter can be 
one of the following values: 


Value Meaning 
0 | The font has read-write permission. 
1 The font has read-only permission and should be hidden from other ap- 


plications in the system. When this flag is set, the font is not enumerated 
by the EnumFonts or EnumFontFamilies function. 


: IpszResourceF ile 
Points to a null-terminated string specifying the name of the font resource file 
that this function creates. 


lpszFontFile 
Points to a null-terminated string specifying the scalable font file this function 
uses to create the font resource file. This parameter must specify either the 
filename and extension or a full path and filename, including drive and 
filename extension. | 


[pszCurrentPath 
Points to a null-terminated string specifying either the path to the scalable font 
file specified in the ipszF ontFile parameter or NULL, if lpszFontF ile specifies 


a full path. 
Return Value The return values is nonzero if the function J is successful. Otherwise, it is zero. 
Comments ~ An application must use the CreateScalableFontResource function to create a 


font resource file before installing an embedded font. Font resource files for fonts 
with read-write permission should use the .FOT filename extension. Font resource 
files for read-only fonts should use a different extension (for example, .FOR) and 
should be hidden from other applications in the system by specifying 1 for the 
fHidden parameter. The font resource files can be installed by using the Add- 
FontResource function. 


Example 
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When the /pszFontFile parameter specifies only a filename and extension, the 
IpszCurrentPath parameter must specify a path. When the [pszFontFile parameter 
specifies a full path, the IpszCurrentPath parameter must be NULL or a pointer to 
NULL. | 


When only a filename and extension is specified in the lpszFontFile parameter and 
a path is specified in the /pszCurrentPath parameter, the string in lpszFontFile is 
copied into the .FOT file as the .TTF file that belongs to this resource. When the © 
AddFontResource function is called, the system assumes that the .TTF file has 
been copied into the SYSTEM directory (or into the main Windows directory in 
the case of a network installation). The .TTF file need not be in this directory 
when the CreateScalableFontResource function is called, because the | 
lpszCurrentPath parameter contains the directory information. A resource created 
in this manner does not contain absolute path information and can be used in any 


Windows installation. 


When a path is specified in the [pszFontFile parameter and NULL is specified in 
the IpszCurrentPath parameter, the string in IpszFontFile is copied into the .FOT 
file. In this case, when the AddFontResource function is called, the .TTF file 
must be at the location specified in the /pszFontFile parameter when the Create- 
ScalableFontResource function was called; the lpszCurrentPath parameter is not 
needed. A resource created in this manner contains absolute references to paths 
and drives and will not work if the .TTF file is moved to a different location. 


The CreateScalableFontResource function supports only TrueType scalable 
fonts. 


The following example shows how to create a TrueType font file in the SYSTEM 


directory of the Windows startup directory: 


CreateScalableFontResource(®@, "c:\\windows\\system\\font. fot", 
"font.ttr", "c:\\windows\\system"); | 


AddFontResource("c:\\windows\\system\\font. fot") ; 


The following example shows how to create a TrueType font file in a specified 


directory: 


CreateScalableFontResource(@, "c:\\windows\\system\\font.fot", 
"ce:\\fontdir\\font.ttr”, NULL); 


- AddFontResource("c:\\windows\\system\\font. fot"); 
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The following example shows how to work with a standard embedded font: 


HFONT hfont; 
/* Extract .TTF file into C:\MYDIR\FONT.TTR. */ 
CreateScalableFontResource(@, "font.fot", "c:\\mydir\\font.ttr", NULL): 
AddFontResource("font. fot"); 
hfont = CreateFont(..., CLIP_DEFAULT_PRECIS, ieee COND Ss 
/* Use the font. */ 
DeleteObject(hfont); | 
L RemoveFontResource("font. fot"); 


. /* Delete C:\MYDIR\FONT.FOT and C:\MYDIR\FONT.TTR. */ 


The following example shows how to work with a read-only embedded font: 
HFONT hfont; 
/* Extract.TIF file into C:\MYDIR\FONT.TTR. */ 
CreateScalableFontResource(1, "font.for", "c:\\mydir\\font.ttr", NULL); 
AddFontResource("font.for"); | 
hfont = CreateFont(..., CLIP_EMBEDDED, ..., “FONT"™); 

/* Use the font. */ | 
Helereoniecechfont)- 
RemoveFontResource("font. for"); 


. /* Delete C:\MYDIR\FONT.FOR and C:\MYDIR\FONT.TTR. */ 


See Also — AddFontResource | 
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CreateSolidBrush [ 2x | 


HBRUSH CreateSolidBrush(clrref) 
COLORREF clrref; /* brush color **/ 


The CreateSolidBrush function creates a brush that has a specified solid color. 
The brush can subsequently be selected as the current brush for any device. 


Parameters clrref 
| Specifies the color of the brush. 


Return Value The return value is the handle of the brush if the function is successful. Otherwise, 
itis NULL. 


Comments When an application has finished using the brush created by suaieauu it 
| should select the brush out of the device context and then remove it by using the 
DeleteObject function. 


Example The following example uses the CreateSolidBrush function to create a green 
- brush, selects the brush into a device context, and then uses the brush to fill a 
rectangle: 


HBRUSH hbrOld; 
HBRUSH hbr; 


— hbr = CreateSolidBrush(RGB(@, 255, @)); 
hbrOld = SelectObject(hdc, hbr); 
Rectangle(hdc, 10, 10, 100, 100); 


See Also CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, 
CreatePatternBrush, DeleteObject 
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CreateWindow 


HWND CreateWindow(IpszClassName, lpszWindowName, dwStyle, x, y, nWidth, nHeight, 
hwndParent, hmenu, hinst, lpvParam) 


Parameters 


LPCSTR IpszClassName; /* address of registered class name 7] 
LPCSTR [pszWindowName; /* address of window text */ 
DWORD dwSple; /* window style | my 
int x; /* horizontal position of window */ 
int y; /* vertical position of window si | 
int nWidth; /* window width | 
int nHeight; | /* window height ri) 
HWND hwndParent; /* handle of parent window yf 
HMENU hmenu; /* handle of menu or child-window identifier */ 
HINSTANCE hinst; /* handle of application instance i 
void FAR* [pvParam; /* address of window-creation data — i 


The Create Window function creates an overlapped, pop-up, or child window. 
The CreateWindow function specifies the window class, window title, window 
style, and (optionally) the initial position and size of the window. The Create- 
Window function also specifies the window’s parent (if any) and menu. | 


[pszClassName 
Points to a null-terminated string specifying the window class. The class name 
can be any name registered with the RegisterClass function or any of the prede- 
fined control-class names. (See the following Comments section for a complete 
list.) 


[pszWindowName 
Points to a null-terminated string that represents the window name. 


dwStyle 


Specifies the style of window being created. This parameter can be ; a combina- 
tion of the window styles and control styles given in the following Comments 
section. | 


Specifies the initial x-position of the window. For an overlapped or pop-up win- 
dow, the x parameter is the initial x-coordinate of the window’s upper-left 
corner, in screen coordinates. For a child window, x is the x-coordinate of the 
upper-left corner of the window in the client area of its parent window. 


If this value is CW_USEDEFAULT, Windows selects the default 
position for the window’s upper-left corner and ignores the y parameter. 
CW_USEDEFAULT 1s valid only for overlapped windows. If 
CW_USEDEFAULT is specified for a non-overlapped window, the x 
and y parameters are set to 0. 
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Specifies the initial y-position of the window. For an overlapped window, the 
y parameter is the initial y-coordinate of the window’s upper-left corner. For a 
pop-up window, y is the y-coordinate, in screen coordinates, of the upper-left 
corner of the pop-up window. For list-box controls, y is the y-coordinate of the 
upper-left corner of the control’s client area. For a child window, y is the _ 
y-coordinate of the upper-left corner of the child window. All of these coordi- 
nates are for the window, not the window’s client area. 


If an overlapped window is created with the WS_VISIBLE style and the x pa- 
rameter set to CW_USEDEFAULT, Windows ignores the y parameter. 


nWidth 


Specifies the width, in device units, of the window. For overlapped windows, 
the nWidth parameter is either the window’s width (in screen coordinates) or 
CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a de- 
fault width and height for the window (the default width extends from the ini- 
tial x-position to the right edge of the screen, and the default height extends 
from the initial y-position to the top of the icon area). CW_USEDEFAULT is 
valid only for overlapped windows. If CW_USEDEFAULT is specified in 
nWidth for a non- ore ae window, nWidth and nHeight are set to 0. 


nHeight 


Specifies the height, in device units, of the window. For overlapped windows, 
the nHeight parameter is the window’s height in screen coordinates. If the 
nWidth parameter is CW_USEDEFAULT, Windows ignores nHeight. 


hwndParent 


Identifies the parent or owner window of the window being created. A valid 
window handle must be supplied when creating a child window or an owned 
window. An owned window is an overlapped window that is destroyed when its 
owner window is destroyed, hidden when its owner is minimized, and that is al- 
ways displayed on top of its owner window. For pop-up windows, a handle can 
_be supplied but is not required. If the window does not have a parent window or 
is not owned by another window, the hwndParent parameter must be set to. 
HWND ~DESKTOP. | 


hmenu 


Identifies a menu or a child window. This parameter’ S meaning depends on the 


window style. For overlapped or pop-up windows, the hmenu parameter identi- 


_ fies the menu to be used with the window. It can be NULL, if the class menu is 
to be used. For child windows, hmenu identifies the child window and is an in- | 
‘teger value that is used by a dialog box control to notify its parent of events 
(such as the EN_HSCROLL message). The child window identifier is deter- 

- mined by the application and should be unique for all child windows with the 
same parent window. 


hinst 


Identifies the instance of the module to be associated with the window: 
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Return Value 


Comments 


[pvParam 
Points to a value that is passed to the window through the CREATESTRUCT 
structure referenced by the /Param parameter of the WM_CREATE message. If 
an application is calling CreateWindow to create a multiple document inter- — 
face (MDJ) client window, [pvParam must point to a CLIENTCREATE- 
STRUCT structure. The CREATESTRUCT structure has the following form: 


typedef struct tagCREATESTRUCT { 
void FAR* 1pCreateParams; 
HINSTANCE hInstance; 


/* cs */ 


HMENU hMenu; 

HWND | hwndParent; 
int cy; 

int CX; 

int y; 

int xs 

LONG style; 
LPCSTR lpszName; 
LPCSTR IpszClass; 
-DWORD dwExStyle; 


} CREATESTRUCT; 


The CLIENTCREATESTRUCT structure has the following form: 


typedef struct tagCLIENTCREATESTRUCT { 
HANDLE hWindowMenu; 
UINT idFirstChild; 

} CLIENTCREATESTRUCT; 


/* ccs */ 


For a full description of these two structures, see the Microsoft Windows Pro- 
grammer’s Reference, Volume 3. 


The return value is the handle of the new window if the function is successful. 
Otherwise, it is NULL. 


For overlapped, pop-up, and child windows, the CreateWindow function sends 
WM_CREATE, WM_GETMINMAXINEFO, and WM_NCCREATE messages to 
the window. If the WS_VISIBLE style is specified, CreateWindow sends the win- 
dow all the messages required to activate and show the window. 


If the window style specifies a title bar, the window title pointed to by the 
[pszWindowName parameter is displayed in the title bar. When using Create- 
Window to create controls such as buttons, check boxes, and edit controls, use the 


[pszWindowName parameter to specify the text of the control. 


Before returning, the CreateWindow function sends a WM_CREATE MmESsabe to 
the window procedure. 
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Following are the predefined control classes an application can specify in the 
[pszClassName parameter: 


Class 
BUTTON 


COMBOBOX 


EDIT 


LISTBOX 


Meaning 


Designates a small rectangular child window that represents a but- 
ton the user can turn on or off by clicking. Button controls can be | 
used alone or in groups, and can either be labeled or appear without 
text. Button controls typically change appearance when the user 
clicks them. 


Designates a control consisting of a list box and a selection field 
similar to an edit control. The list box may be displayed at all times 
or may be dropped down when the user selects a pop-up list box | 
next to the selection field. 


Depending on the style of the combo box, the user can or cannot 
edit the contents of the selection field. If the list box is visible, 
typing characters into the selection box will cause the first list box 
entry that matches the characters typed to be highlighted. Con- 
versely, selecting an item in the list box displays the selected text in 
the selection field. 


Designates a rectangular child window in which the user can type 


text from the keyboard. The user selects the control, and gives it the 
input focus by clicking it or moving to it by pressing the TAB key. 
The user can type text when the control displays a flashing caret. 


-The mouse can be used to move the cursor and select characters to 


be replaced, or to position the cursor for inserting characters. The 
BACKSPACE key can be used to delete characters. 


Edit controls use the variable-pitch System font and display charac- _ 
ters from the Windows character set. Applications compiled to run 
with earlier versions of Windows display text with a fixed-pitch Sys- 
tem font unless they have been marked by the Windows 3.0 MARK 
utility (with the MEMORY FONT option specified). An applica- 
tion can also send the WM_SETFONT message to the edit control 
to change the default font. 


Edit controls expand tab characters into as many space characters as _ 
are required to move the cursor to the next tab stop. Tab stops are as- 
sumed to be at every eighth character position. , 


Designates a list of character strings. This control is used whenever 
an application must present a list of names, such as filenames, from 
which the user can choose. The user can select a string by pointing 
to it and clicking. When a string is selected, it is highlighted and a 
notification message is passed to the parent window. A vertical or 
horizontal scroll bar can be used with a list box control to scroll lists 


_ that are too long for the control window. The list box automatically 
hides or shows the scroll bar as needed. 
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Class | Meaning 


MDICLIENT Designates an MDI client window. The MDI client window receives 
messages that control the MDI application’s child windows. The rec- 
ommended style bits are WS_CLIPCHILDREN and WS_CHILD. 
To create a scrollable MDI client window that allows the user to 
scroll MDI child windows into view, an application can also use the 
WS_HSCROLL and WS_VSCROLL styles. — 


SCROLLBAR Designates a rectangle that contains a scroll box (also called a 
“thumb”’) and has direction arrows at both ends. The scroll bar sends 
a notification message to its parent window whenever the user clicks 
the control. The parent window is responsible for updating the posi- 
tion, if necessary. Scroll bar controls have the same appearance and 
function as scroll bars used in ordinary windows. Unlike scroll bars, 
however, scroll bar controls can be positioned anywhere in a win- 
dow and used whenever needed to provide scrolling input for a 
window. : 
The scroll bar class also includes size box controls (Maximize and 
Minimize buttons). These controls are small rectangles that the user 
can click to change the size of the window. 

STATIC Designates a simple text field, box, or rectangle that can be used to 
label, box, or separate other controls. Static controls take no input 
and provide no output. 


Following are the window styles an application can specify in the dwStyle 


parameter. 

Style Meaning 

MDIS_ALLCHILDSTYLES Creates an MDI child window that can have any 
combination of window styles. When this style is 
not specified, an MDI child window has the 
WS_MINIMIZE, WS_MAXIMIZE, 
WS_HSCROLL, and WS_VSCROLL styles 
as default settings. 

WS_BORDER- © Creates a window that has a border. 

WS_CAPTION Creates a window that has a title bar (implies the 

~ WS_BORDER style). This style cannot be used 

| with the WS_DLGFRAME style. | 

WS_CHILD _ Creates a child window. Cannot be used with the 
WS_POPUP style. | 

WS_CHILDWINDOW Same as the WS_CHILD style. 

WS_CLIPCHILDREN Excludes the area occupied by child windows 


when drawing within the parent window. Used 
when creating the parent window. 


Style 
WS_CLIPSIBLINGS 


~ WS_DISABLED 
WS_DLGFRAME 
WS_GROUP 


WS_HSCROLL 
WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS. MINIMIZE 


WS_MINIMIZEBOX 
WS_OVERLAPPED 


WS_OVERLAPPEDWINDOW 


-WS_ POPUP 


~WS_POPUPWINDOW 


WS_SYSMENU 
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Meaning 


Clips child windows relative to each other; that is, 
when a particular child window receives a paint 
message, the WS_CLIPSIBLINGS style clips all 
other overlapped child windows out of the 

region of the child window to be updated. (If 
WS_CLIPSIBLINGS is not specified and child 
windows overlap, it is possible, when drawing 
within the client area of a child window, to draw 
within the client area of a neighboring child win- 
dow.) For use with the WS_CHILD style only. 


Creates a window that is initially disabled. 
Creates a window with a double border but no title. 


Specifies the first control of a group of controls in 
which the user can move from one control to the 
next by using the arrow keys. All controls defined 
with the WS_GROUP style after the first control 
belong to the same group. The next control with 
the WS_GROUP style ends the style group and 
starts the next group (that is, one group ends 
where the next begins). Only dialog boxes use this 
style. 


Creates a window that has a horizontal scroll bar. 
Creates a window of maximum size. 
Creates a window that has a Maximize button. 


Creates a window that is initially minimized. For 
use with the WS_OVERLAPPED style only. 


Creates a window that has a Minimize button. 


Creates an overlapped window. An overlapped 
window has a title and a border. 


Creates an overlapped window having the ~ 
WS_OVERLAPPED, WS_CAPTION, 
WS_SYSMENU, WS_THICKFRAME, 
WS_MINIMIZEBOX, and WS_MAXIMIZEBOX 
styles. 


Creates a pop-up window. Cantos be used with the 
WS_CHILD style. — 


Creates a pop-up window that has the 
WS_BORDER, WS_POPUP, and 
WS_SYSMENU styles. The WS _CAPTION style 
must be combined with the 
WS_POPUPWINDOW style to make the System 
menu visible. 


Creates a window that has a Gy stern visti box in 
its title bar. Used only for windows with title bars. 
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Style 


WS_TABSTOP 


WS_THICKFRAME 


WS_ VISIBLE 


WS_VSCROLL 


Meaning 


Specifies one of any number of controls through | 
which the user can move by using the TAB key. 
The TAB key moves the user to the next control 
specified by the WS_TABSTOP style. Only dialog 
boxes use this style. : 


Creates a window with a thick frame that can be 
used to size the window. 


Creates a window that is initially visible. This ap- 
plies to overlapped, child, and pop-up windows. 
For overlapped windows, the y parameter is used 
as a ShowWindow function parameter. 


Creates a window that has a vertical scroll bar. 


Following are the button styles (in the BUTTON class) that an application can 
specify in the dwStyle parameter: 


Value 
BS_3STATE 


BS_AUTO3STATE 


BS_AUTOCHECKBOX 


BS_AUTORADIOBUTTON 


-BS_CHECKBOX 


BS_DEFPUSHBUTTON 


BS_GROUPBOX 


Meaning 


Creates a button that is the same as a check box, ex- 
cept that the box can be grayed (dimmed) as well as 
checked. The grayed state is used to show that the 
state of a check box is not determined. 


Creates a button that is the same as a three-state 
check box, except that the box changes its state when 
the user selects it. The state cycles through checked, 
grayed, and normal. 


Creates a button that is the same as a check box, ex- 
cept that an X appears in the check box when the user 
selects the box; the X disappears (is cleared) the next 
time the user selects the box. 


Creates a button that is the same as a radio button, ex- 
cept that when the user selects it, the button automat- 
ically highlights itself and clears (removes the 
selection from) any other buttons in the same group. 


Creates a small square that has text displayed to its 
right (unless this style is combined with the 
BS_LEFTTEXT style). | 


Creates a button that has a heavy black border. The 
user can select this button by pressing the ENTER key. 
This style is useful for enabling the user to quickly 
select the most likely option (the default option). 


Creates a rectangle in which other controls can be 
grouped. Any text associated with this style is dis- 
played in the rectangle’s upper-left corner. 


Value 


~BS_LEFTTEXT 


BS_OWNERDRAW 


BS_PUSHBUTTON 


BS_RADIOBUTTON 
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Meaning 


Places text on the left side of the radio button or 
check box when combined with a radio button or 
check box style. 


Creates an owner-drawn button. The owner window 
receives a WM_MEASUREITEM message when the 
button is created, and it receives a 
WM_DRAWITEM message when a visual eet of 
the button has changed. The BS_OWNERDRAW 
style cannot be combined with any other button 
styles. 


Creates a push button that posts a WM_COMMAND | 
message to the owner window when the user selects 
the button. 


Creates a small circle that has text displayed to its _ 
right (unless this style is combined with the 
BS_LEFTTEXT style). Radio buttons are usually 
used in groups of related but mutually exclusive 
choices. 


Following are the combo box styles (in the COMBOBOX class) that an applica- _ 
tion can specify in the dwStyle parameter: 


Style 
CBS_AUTOHSCROLL 


CBS. DISABLENOSCROLL 


-CBS_DROPDOWN 
CBS_DROPDOWNLIST 


CBS_HASSTRINGS 


Description 


Automatically scrolls the text in the edit con- 
trol to the right when the user types a character 
at the end of the line. If this style is not set, 
only text that fits within the rectangular bound- 
ary is allowed. 


Shows a disabled vertical scroll bar in the list 
box when the box does not contain enough 
items to scroll. Without this style, the scroll bar 
is hidden when the list box does not contain 
enough items. 


Similar to CBS_SIMPLE, except that the list 
box is not displayed unless the user selects an 
icon next to the edit control. | 


Similar to CBS_DROPDOWN, except that the 
edit control is replaced by a static text item that 
displays the current selection in the list box. 


Specifies that an owner-drawn combo box con- 
tains items consisting of strings. The combo 

box maintains the memory and pointers for 
the strings so the application can use the 
-CB_GETLBTEXT message to retrieve the 

text fora 1 particular item. 
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Style Description 


CBS_NOINTEGRALHEIGHT Specifies that the size of the combo box is ex- 
| actly the size specified by the application when 
it created the combo box. Normally, Windows 
sizes a combo box so that the combo box does 
not display partial items. 


CBS_OEMCONVERT Converts text entered in the combo-box edit 
| control from the Windows character set to the 
‘ OEM character set and then back to the Win- 
dows set. This ensures proper character conver- 
sion when the application calls the 
AnsiToOem function to convert a Windows 
string in the combo box to OEM characters. 
This style is most useful for combo boxes that 
contain filenames and applies only to combo 
boxes created with the CBS_ SIMPLE or 
CBS_DROPDOWN styles. 


| CBS_OWNERDRAWFIXED Specifies that the owner of the list box is re- 


sponsible for drawing its contents and that the 
items in the list box are all the same height. 
The owner window receives a 

~ WM_MEASUREITEM message when the 
combo box is created and a WM_DRAWITEM 
message when a visual aspect of the combo 
box changes. 


CBS_OWNERDRAWVARIABLE Specifies that the owner of the list box is re- 
sponsible for drawing its contents and that the 
items in the list box are variable in height. The 
owner window receives a WM_MEASURE- 
ITEM message for each item in the combo 
box when the combo box is created and a 
WM_DRAWITEM message when a visual 
aspect of the combo box changes. 


CBS_SIMPLE Displays the list box at all times. The current 


selection in the list box is displayed in the edit 
control. | 
CBS_SORT Automatically sorts strings entered into the list — 
| | box. | 


Following are the edit control styles (in the EDIT class) that an application can 


specify in the dwStyle parameter: | 


Style Meaning 


ES_AUTOHSCROLL Automatically scrolls text to the right by 10 characters when 
_ the user types a character at the end of the line. When the 
user presses the ENTER key, the control scrolls all text back 
to position zero. 


Style 
ES_AUTOVSCROLL 


ES_CENTER 
ES_LEFT 
ES_LOWERCASE 


ES_MULTILINE 


ES_NOHIDESEL 


ES_OEMCONVERT 
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Meaning 


Automatically scrolls text up one page when the user 
presses ENTER on the last line. 


Centers text in a multiline edit control. 
Left aligns text. 


Converts all characters to lowercase as they are typed into 
the edit control. 


Designates a multiline edit control. (The default 1 is single- 
line edit control.) 


When a multiline edit control is in a dialog box, the default 
response to pressing the ENTER key 1s to activate the default 
button. To use the ENTER key as a carriage return, an appli- 
cation should use the ES_WANTRETURN style. 


When the multiline edit control is not in a dialog box and 
the ES_AUTOVSCROLL style is specified, the edit control 
shows as many lines as possible and scrolls vertically when 
the user presses the ENTER key. If ES_AUTOVSCROLL 

is not specified, the edit control shows as many lines as 
possible and beeps if the user presses ENTER when no more 
lines can be displayed. 

If the ES_AUTOHSCROLL style is specified, the auleitine 


edit control automatically scrolls horizontally when the 
caret goes past the right edge of the control. To start a new 
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line, the user must press ENTER. If ES_AUTOHSCROLL 1s | 


not specified, the control automatically wraps words to the 
beginning of the next line when necessary. A new line is 


also started if the user presses ENTER. The position of the 


wordwrap is determined by the window size. If the window 
size changes, the wordwrap position changes and the text I 1S 
redisplayed. 


Multiline edit controls can have scroll bars. An edit control 
with scroll bars processes its own scroll bar messages. Edit 
controls without scroll bars scroll as described in the pre- 
vious two paragraphs and process any scroll messages sent 
by the parent window. 


Negates the default behavior for an edit control. The default 
behavior is to hide the selection when the control loses the 
input focus and invert the selection when the control re- 
ceives the input focus. 


Converts text entered in the edit atl from the Windows 
character set to the OEM character set and then back to the 
Windows set. This ensures proper character conversion 
when the application calls the AnsiToOem function to con- 


vert a Windows string in the edit control to OEM characters. 


This style is most ea for edit controls that contain 


| filenames. 
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Style 
ES_PASSWORD 


ES_ READONLY 


ES_RIGHT 
ES_UPPERCASE 


ES_WANTRETURN 


Meaning 


Displays all characters as an asterisk (*) as they are typed 
into the edit control. An application can use the 
EM_SETPASSWORDCHAR message to change the charac- 
ter that is displayed. 


Prevents the user from typing or editing text in the edit con- 
trol. 


Right aligns text in a multiline edit control. 


Converts all characters to uppercase as they are typed into 
the edit control. 


Specifies that a carriage return be inserted when the user 
presses the ENTER key while entering text into a multiline 
edit control in a dialog box. If this style is not specified, 
pressing the ENTER key has the same effect as pressing the 
dialog box’s default push button. This style has no effect on 
a single-line edit control. 


Following are the list box styles (in the LISTBOX class) that an application can 
specify in the dwStyle parameter: 


Style 


Meaning 


LBS_DISABLENOSCROLL Shows a disabled vertical scroll bar for the list 


LBS_EXTENDEDSEL 


LBS_HASSTRINGS 


LBS_MULTICOLUMN 


~ LBS_MULTIPLESEL 


box when the box does not contain enough 
items to scroll. If this style is not specified, the 
scroll bar is hidden when the list box does not 
contain enough items. | 


Allows multiple items to be selected by using 
the SHIFT key and the mouse or special key 
combinations. 


Specifies that a list box contains items con- 
sisting of strings. The list box maintains the 
memory and pointers for the strings so the ap- 
plication can use the LB_GETTEXT message 
to retrieve the text for a particular item. By de- 
fault, all list boxes except owner-drawn list 
boxes have this style. An application can create 
an owner-drawn list box either with or without 
this style. 

- Specifies a multicolumn list box that is scrolled 
horizontally. The LB_SETCOLUMNWIDTH 
message Sets the width of the columns. 

Turns string selection on or off each time the 
user clicks or double-clicks the string. Any 
number of strings can be selected. | 


Style 
LBS_NOINTEGRALHEIGHT 


LBS_NOREDRAW 


LBS_NOTIFY 


LBS_OWNERDRAWFIXED 


LBS_OWNERDRAWVARIABLE 


LBS_SORT | 
LBS_STANDARD 


LBS_USETABSTOPS 
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Meaning 


Specifies that the size of the list box is exactly 
the size specified by the application when it 
created the list box. Normally, Windows sizes a 
list box so that the list box does not display par- 
tial items. 


Specifies that the list box’s appearance is not 
updated when changes are made. This style 
can be changed at any time by sending a 
WM_SETREDRAW message. 


Notifies the parent window with an input mes- 
sage whenever the user clicks or double-clicks 
a string. 


Specifies that the owner of the list box is re- 


sponsible for drawing its contents and that the 


items in the list box are the same height. The 
owner window receives a WM_MEASURE- 
ITEM message when the list box is created and 
a WM_DRAWITEM message when a visual 
aspect of the list box changes. | 


Specifies that the owner of the list box is 
responsible for drawing its contents and — 

that the items in the list box are variable in 
height. The owner window receives a 
WM_MEASUREITEM message for each item 


- 1n the list box when the list box is created and a 


WM_DRAWITEM message whenever the | 
visual aspect of the list box changes. 


Sorts strings in the list box alphabetically. 


Sorts strings in the list box alphabetically. The 
parent window receives an input message 
whenever the user clicks or double-clicks a 
string. The list box has borders on all sides. 


Allows a list box to recognize and expand tab 
characters when drawing its strings. The de- 
fault tab positions are 32 dialog box units. (A 
dialog box unit is a horizontal or vertical dis- 
tance. One horizontal dialog box unit is equal 
to one-fourth of the current dialog box base 
width unit. The dialog box base units are com- 
puted based on the height and width of the cur- 
rent system font. The GetDialogBaseUnits 
function returns the current dialog box base 
units in pixels.) 
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Style | Meaning 


LBS_WANTKEYBOARDINPUT Specifies that the owner of the list box receives 
a WM_VKEYTOITEM or WM_CHARTOITEM 

messages whenever the user presses a key and 
the list box has the input focus. This allows an 
application to perform special processing on 
the keyboard input. If a list box has the 
LBS_HASSTRINGS style, the list box can re- 
ceive WM_VKEYTOITEM messages but not 
WM_CHARTOITEM messages. If a list box 
does not have the LBS_HASSTRINGS style, 
the list box can receive WM_CHARTOITEM 
messages but not WM_VKEYTOITEM mes- 
sages. 


Following are the scroll bar styles (in the SCROLLBAR class) that an application 
can specify in the dwStyle parameter: 


Style Meaning 


SBS_BOTTOMALIGN Aligns the bottom edge of the scroll bar 
. with the bottom edge of the rectangle de- 
fined by the following CreateWindow 
parameters: x, y, nWidth, and nHeight. 
The scroll bar has the default height for 
system scroll bars. Used with the 
SBS_HORZ style. 


_ SBS_HORZ Designates a horizontal scroll bar. If 


neither the SBS_BOTTOMALIGN nor 
SBS_TOPALIGN style is specified, the 
scroll bar has the height, width, and posi- 
tion specified by the CreateWindow pa- 
rameters. | 


-SBS_LEFTALIGN Aligns the left edge of the scroll bar 


with the left edge of the rectangle de- 
fined by the CreateWindow parameters. 
The scroll bar has the default width for 
system scroll bars. Used with the 
SBS_VERT style. 


Style 
_ SBS_RIGHTALIGN 


SBS_SIZEBOX 


SBS_SIZEBOXBOTTOMRIGHTALIGN 


SBS_SIZEBOXTOPLEFTALIGN 


SBS_TOPALIGN 


SBS_VERT 
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Meaning 


Aligns the right edge of the scroll bar — 
with the right edge of the rectangle de- 
fined by the CreateWindow parameters. 


- The scroll bar has the default width for 


system scroll bars. Used with the 
SBS_VERT style. 


Designates a size box. If neither the 
SBS_SIZEBOXBOTTOMRIGHTALIGN 
nor SBS_SIZEBOXTOPLEFTALIGN 
style is specified, the size box has the 
height, width, and position specified by 
the CreateWindow parameters. 

Aligns the lower-right corner of the size 
box with the lower-right corner of the 
rectangle specified by the Create- 
Window parameters. The size box has 
the default size for system size boxes. 
Used with the SBS_SIZEBOX style. 


Aligns the upper-left corner of the size 
box with the upper-left corner of the 
rectangle specified by the following 
CreateWindow parameters: x, y, 
nWidth, and nHeight. The size box has 
the default size for system size boxes. 
Used with the SBS_SIZEBOX style. 


Aligns the top edge of the scroll bar 


- with the top edge of the rectangle de- 


fined by the CreateWindow parameters. 
The scroll bar has the default height for 
system scroll bars. Used with the. 
SBS_HORZ style. | 


Designates a vertical scroll bar. If 
neither the SBS_RIGHTALIGN nor | 
SBS_LEFTALIGN style is specified, the 
scroll bar has the height, width, and posi- 
tion specified by the CreateWindow pa- 
rameters. 


144, 


CreateWindow 


Following are the static control styles (in the STATIC class) that an application 
can specify in the dwStyle parameter. A static control can have only one of these 


styles. 
Style 
SS_BLACKFRAME 


SS_BLACKRECT 


SS_CENTER 


SS_GRAYFRAME 
SS_GRAYRECT 


SS_ICON 
SS_LEFT 


SS_LEFTNOWORDWRAP 


SS_NOPREFIX 


Meaning 


Specifies a box with a frame drawn in the same color 
as window frames. This color is black in the default 
Windows color scheme. 


Specifies a rectangle filled with the color used to draw 
window frames. This color is black in the default Win- 
dows color scheme. 


Designates a simple rectangle and displays the given 
text centered in the rectangle. The text is formatted 
before it is displayed. Words that would extend past 
the end of a line are automatically wrapped to the 
beginning of the next centered line. 


Specifies a box with a frame drawn with the same 
color as the screen background (desktop). This color 
is gray in the default Windows color scheme. 


Specifies a rectangle filled with the color used to fill 
the screen background. This color is gray in the de- 
fault Windows color scheme. 


Designates an icon displayed in the dialog box. The 
given text is the name of an icon (not a filename) de- 
fined elsewhere in the resource file. The nWidth and 
nHeight parameters are ignored; the icon automat- 
ically sizes itself. 

Designates a simple rectangle and displays the given 
text left-aligned in the rectangle. The text is formatted 
before it is displayed. Words that would extend past 
the end of a line are automatically wrapped to the 
beginning of the next left-aligned line. 


Designates a simple rectangle and displays the given 
text left-aligned in the rectangle. Tabs are expanded 
but words are not wrapped. Text that extends past the — 
end of a line is clipped. 


Prevents interpretation of any & characters in the con- 


-trol’s text as accelerator prefix characters (which are 


displayed with the & removed and the next character 
in the string underlined). This static control style may 
be included with any of the defined static controls. 


You can combine SS_NOPREFIX with other styles by 
using the bitwise OR operator. This is most often used 
when filenames or other strings that may contain an & 
need to be displayed in a static control in a dialog box. 


See Also 


Style 
SS_RIGHT 


SS_SIMPLE 


SS_WHITEFRAME 


SS_WHITERECT 


rameter: 


Style 
DS_LOCALEDIT 


DS_MODALFRAME 
DS_NOIDLEMSG 


DS_SYSMODAL 
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Meaning 


Designates a simple rectangle and displays the given 
text right-aligned in the rectangle. The text is for- 
matted before it is displayed. Words that would extend 
past the end of a line are automatically wrapped to the 
beginning of the next right-aligned line. 


Designates a simple rectangle and displays a single 
line of text left-aligned in the rectangle. The line of 
text cannot be shortened or altered in any way. (The 
control’s parent window or dialog box must not 
process the WM_CTLCOLOR message.) 


Specifies a box with a frame drawn in the same color 
as window backgrounds. This color is white in the de- 
fault Windows color scheme. 


Specifies a rectangle filled with the color used to fill 
window backgrounds. This color is white in the de- 
fault Windows color scheme. 


Following are the dialog box styles an application can specify in the dwStyle pa- 


Meaning 


Specifies that edit controls in the dialog box will use 
memory in the application’s data segment. By default, all — 
edit controls in dialog boxes use memory outside the applica- 
tion’s data segment. This feature may be suppressed by 
adding the DS_LOCALEDIT flag to the Style command for 
the dialog box. If this flag is not used, EM_GETHANDLE 
and EM_SETHANDLE messages must not be used, because 
the storage for the control is not in the application’s data seg- 
ment. This feature does not affect edit controls created out- 
side of dialog boxes. | 


Creates a dialog box with a modal dialog box frame that can 


be combined with a title bar and System menu by specifying 


the WS_CAPTION and WS_SYSMENU styles. 


_ Suppresses WM_ENTERIDLE messages that Windows 


would otherwise send to the owner of the dialog box while 
the dialog box is displayed. 


Creates a system-modal dialog box. 


| 


AnsiToOem, GetDialogBaseUnits, ShowWindow 
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CreateWindowEx ee 


HWND CreateWindowEx(dwExStyle, lpszClassName, lpszWindowName, dwStyle, x, y, nWidth, 
nHeight, hwndParent, hmenu, hinst, lpvCreateParams) 


DWORD dwExSple; /* extended window style a 
LPCSTR [pszClassName; /* address of registered class name — */ 
LPCSTR /pszWindowName; /* address of window text **/ 
DWORD dwSple; | /* window style : | */ 
int x; | /* horizontal position of the window sa 
int y; /* vertical position of the window i 
int nWidth; | /* window width */ 
int nHeight; /* window height rn | 
HWND hwndParent; /* handle of parent window */ 
HMENU hmenu; /* handle of menu or child-window identifier +/ 
HINSTANCE hinst; /* handle of application instance | a 


_ void FAR* lpvCreateParams; /* address of window-creation data 3 ey 


The CreateWindowKEx function creates an overlapped, pop-up, or child window 
with an extended style; otherwise, this function is identical to the CreateWindow 
function. For more information about creating a window and for full descriptions 
of the other parameters of CreateWindowE*x, see the preceding description of the 
CreateWindow function. | 


Parameters dwExStyle 
Specifies the extended style of the window. This parameter can be one of the 
following values: 
Style | ‘Meaning 
WS_EX_ACCEPTFILES Specifies that a window created with this style 


accepts drag-drop files. 


WS_EX_ DLGMODALFRAME Designates a window with a double border that 
may (optionally) be created with a title bar by 
specifying the WS_CAPTION ad flag in the 
dwStyle parameter. 


WS_EX_NOPARENTNOTIFY Specifies that a child window created by Using 
this style will not send the 
WM_PARENTNOTIPY message to its parent 
window when the child window is created or 
destroyed. 


WS_EX_ TOPMOST Specifies that a window created with this style 
| | _ should be placed above all non-topmost win- 
dows and stay above them even when the win- 
dow is deactivated. An application can use the 
SetWindowPos function to add or remove this 
attribute. 
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Style ; Meaning 


WS_EX_TRANSPARENT Specifies that a window created with this style 
is to be transparent. That is, any windows that 
are beneath the window are not obscured by 
the window. A window created with this style 
receives WM_PAINT messages only after all 
sibling windows beneath it have been updated. 


lpszClassName | 
Points to a null-terminated string containing the name of the window class. 


lpszWindowName 
Points to a null- terminated string containing the name of the now: 


dwStyle 
Specifies the style of the window. For a list of the window styles that can be 
specified in this parameter, see the preceding description of the CreateWindow 
function. 


qs! | a 
Specifies the initial left-side position of the window. 


Specifies the initial top position of the window. 


nWidth 
Specifies the width, in device units, of the window. 


nHeight 
Specifies the height, in device units, of the window. 


hwndParent 
Identifies the patent or owner window of the window to be created. 


hmenu — 3 
Identifies a menu or a child window. The meaning depends on the window 
‘Style. | 


hinst — 
Identifies the instance of the module to be associated with the window. 


[pvCreateParams _ 
Contains any application-specific creation parameters. The window being 
created may access this data when the CREATESTRUCT structure is passed 
to the window by the WM_NCCREATE and WM_CREATE messages. 
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Return Value 


Comments 


Example 


See Also 


The CREATESTRUCT structure has the following form: 


typedef struct tagCREATESTRUCT { /* cs */ 
void FAR* IpCreateParams; 
HINSTANCE hInstance; 


HMENU hMenu;. 
HWND hwndParent; 
int Cys 

int CX; 

int y3 

int x: 

LONG style; 


LPCSTR TpszName; 

LPCSTR lpszClass; 

DWORD dwExStyle; 
} CREATESTRUCT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


The return value identifies the new window if the function is successful. Other- 
wise, itis NULL. 


The CreateWindowE*x function sends the following messages to the window 
being created: 


WM_NCCREATE 
WM_NCCALCSIZE 
WM_CREATE 


The following example creates a main window that has the WS_EX_TOPMOST 
extended style, makes the window visible, and updates the window’s client area: 


char szClassName[] = "MyClass"; 
/* Create the main window. */ 


hwnd = CreateWindowEx(WS_EX_TOPMOST, szClassName, "Grouper", 
WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, 
~CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, 
hinst, NULL); 


/* Make the window visible and update its client area. */ 


~ ShowWindow(hwnd, SW_ SHOW); /* always show the window */ 


UpdateWindow( hwnd) ; 


CreateWindow, SetWindowPos 
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DdeAbandonTransaction EXE) 


#include <ddeml.h> 


BOOL DdeAbandonTransaction(idInst, hConv, idTransaction) 
DWORD id/nst; /* instance identifier | si 

- HCONV hConv; /* handle of conversation */ 
DWORD idTransaction; _/* transaction identifier */ 


The DdeAbandonTransaction function abandons the specified asynchronous 
transaction and releases all resources associated with the transaction. 


Parameters idInst 
Specifies the application-instance identifier obtained by-4 a previous call to the 
Ddelnitialize function. 


hConv 
Identifies the conversation in which the transaction \ was initiated. If this parame- 
ter is NULL, all transactions are abandoned (the idTransaction parameter 1s 1g- 
nored). | , . 


idTransaction | | a 
Identifies the transaction to terminate. if this parameter is NULL, all active 
transactions in the specified conversation are abandoned. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Errors Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 
DMLERR_UNFOUND_QUEUE_ID 


Comments Only a dynamic data exchange (DDE) client application should call the Dde- 
AbandonTransaction function. If the server application responds to the transac- 
tion after the client has called DdeAbandonTransaction, the system discards the 
transaction results. This function has no effect on synchronous transactions. 


See Also DdeClientTransaction, DdeGetLastError, Ddelnitialize, DdeQueryConvinfo 
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DdeAccessData 


#include <ddeml.h> 


BYTE FAR* DdeAccessData(hData, I[pcbData) 


HDDEDATA Data; 


/* handle of global memory object */ 


DWORD FAR* IpcbData; /* pointer to variable that receives data length a 


Parameters 


Return Value 


Errors 


Comments 


The DdeAccessData function provides access to the data in the given global 
memory object. An application must call the DdeUnaccessData function when it 
is finished accessing the data in the object. 


hData | 
Identifies the global memory object to access. 


lpcbData 
Points to a variable that receives the size, in bytes, of the global memory object 
identified by the hData parameter. If this panier iS ae, no size informa- 
tion is returned. 


The return value points to the first byte of data in the global memory object if the 
function is successful. Otherwise, the return value is NULL. 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: | 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 


If the hData parameter has not been passed to a Dynamic Data Exchange Manage- 
ment Library (DDEML) function, an application can use the pointer returned by 
DdeAccessData for read-write access to the global memory object. If hData has 
already been passed to a DDEML function, the pointer can only be used for read- 


| only access to the memory object. 


Example 


The following example uses the DdeAccessData function to obtain a pointer to a 
global memory object, uses the pointer to copy data from the object to a local buff- 
er, then frees the co 


HDDEDATA hData;_ 

LPBYTE lpszAdviseData; 
DWORD cbDataLen; 

DWORD i; 

char szDatal128]; 


_IpszAdviseData = DdeAccessData(hData, &cbDataLen); 


See Also 


DdeAddData 


#include <ddeml.h> 
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for (i = @; i < cbDataLen; i++) 


szDataLi] = *IpszAdviseDatat+; 
pdepeee cssbalanilelad: 


DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle, DdeGetLast- 


Error, DdeUnaccessData 


HDDEDATA DdeAddData(hData, lpvSrcBuf, cbAddData, offObj) 
HDDEDATA hData; /* handle of global memory object **/ 
void FAR* IpvSrcBuf; /* address of source buffer */ 
DWORD cbAddData; /* length of data | 
/* offset within global memory object */ 


DWORD offObj; 


Parameters 


Return Value 


The DdeAddData function adds data to the given global memory object. An appli- 
cation can add data beginning at any offset from the beginning of the object. If 
new data overlaps data already in the object, the new data overwrites the old data 
in the bytes where the overlap occurs. The contents of locations in the object that . 
have not been written to are undefined. | 


hData 
Identifies the global memory object that receives additional data, 


lpvSrcBuf 
Points to a buffer containing the data to add to the global memory object. 


cbAddData 
Specifies the length, in bytes, of the data to be added to the global memory ob- 
ject. | 
offObj 
Specifies an offset, in bytes, from the beginning of the global memory object. 
The additional data is copied to the object beginning at this offset. 


The return value; is anew handle of the elobal memory ahieet if the function is - 


_ successful. The new handle should be used in all references to the ebivet The re- 


— turn value is Zero if an error occurs. 


Errors 


Use the DdeGetLastError function to retrieve the error value, which may be one 


of the following: 
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DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_MEMORY_ERROR 
DMLERR_NO_ERROR 


Comments After a data handle has been used as a parameter in another Dynamic Data Ex- 
| change Management Library (DDEML) function or returned by a DDE callback 
function, the handle may only be used for read access to the global memory object 
identified by the handle. 


If the amount of global memory originally allocated is not large enough to hold 
the added data, the DdeAddData function will reallocate a global memory object 
of the appropriate size. 


Example The following example creates a global memory object, uses the DdeAddData 
function to add data to the object, and then passes the data to a client with an 
XTYP_POKE transaction: 


DWORD idInst; /* instance identifier * / 
HDDEDATA hddeStrings; /* data handle * / 
HSZ hszMyIten; /* jtem-name string handle */ 
DWORD off0bj = Q; /* offset in global object */ 
char szMyBuf[16]; /* temporary string buffer */ 
HCONV hconv; /* conversation handle * / 
DWORD dwResult; /* transaction results * / 
BOOL fAddAString; /* TRUE if strings to add */ 


/* Create a global memory object. */ 


hddeStrings = DdeCreateDataHandle(idInst, NULL, 0, @, 
hszMyItem, CF_TEXT, @); 


/* 

* If a string is available, the application-defined function 

* IsThereAString() copies it to szMyBuf and returns TRUE. Otherwise, 
* jt returns FALSE. 

7 / 


while ((fAddAString = IsThereAString())) { 


/* Add the string to the global memory object. */ 


DdeAddData(hddeStrings, _ /* data handle ok] 
&sZzMyBuf , yp ae | /* string buffer —R/ 
(DWORD) strilen(szMyBuf) + 1, =/#* character count * / 
off0bj); /* offset in object * / 


offObj = (DWORD) strlen(szMyBuf) + 1; /* adjust offset */ 
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/* No more data to add, so poke it to the server. */ 


DdeClientTransaction((void FAR*) hddeStrings, -1L, hconv, hszMyItem, 
CF_TEXT, XTYP_POKE, 1000, &dwResult); 


See Also DdeAccessData, DdeCreateDataHandle, DdeGetLastError, DdeUnaccessData 


DdeCallback ee oe — faa] 


#include <ddeml.h> 
HDDEDATA CALLBACK DdeCallback(type, fmt, hconv, hsz1, hsz2, hData, dwData1l, awDaee):* 
UINT type; | /* transaction type sd 
—UINT fmt; /* clipboard data format ey 
HCONV hconv; /* handle of conversation */ 
HSZ hszl; _ /* handle of string **/ 
HSZ hsz2; /* handle of string - */ 
~ HDDEDATA hData; /* handle of global memory object */ 
DWORD dwDatal; /* transaction-specific data — */ 
DWORD dwData2; /* transaction-specific data a ae 


The DdeCallback function is an application-defined dynamic data exchange 8 
(DDE) callback function that processes DDE transactions sent to the function as a_ 
result of DDE Management Library (DDEML) calls by other applications. 


Parameters type 
| Specifies the type of the current transaction. This parameter consists of a ‘combi- 
nation of transaction-class flags and transaction-type flags. The following table 
describes each of the transaction classes and provides a list of the transaction 
types in each class. For information about a specific transaction type, see the in- 
dividual description of that type in the Microsoft Windows Programmer’ Ss Refer-— 
ence, Volume 3. 7 


Value : | Meaning 


XCLASS_BOOL A DDE callback function should return TRUE or 
| FALSE when it finishes processing a transaction — 
that belongs to this class. Following are the _ 
XCLASS_BOOL transaction types: | 


XTYP_ADVSTART 
XTYP_CONNECT 
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Value Meaning 


XCLASS_DATA A DDE callback function should return a DDE data 
handle, CBR_BLOCK, or NULL when it finishes 
processing a transaction that belongs to this class. 
Following are the XCLASS_DATA transaction 
types: 

XTYP_ADVREQ 
XTYP_REQUEST 
XTYP_WILDCONNECT _ 

XCLASS_FLAGS A DDE callback function should return 
DDE_FACK, DDE_FBUSY, or 
DDE_FNOTPROCESSED when it finishes 
processing a transaction that belongs to this 
class. Following are the XCLASS_FLAGS 
transaction types: 

XTYP_ADVDATA 
XTYP_EXECUTE 
XTYP_POKE 

XCLASS_NOTIFICATION The transaction types that belong to this class are 
for notification purposes only. The return value 
from the callback function is ignored. Following 
are the XCLASS_NOTIFICATION transaction 
types: 

_ XTYP_ADVSTOP 
XTYP_CONNECT_CONFIRM 
XTYP_DISCONNECT | 
XTYP_ERROR 
XTYP_MONITOR 
XTYP_REGISTER : 
XTYP_XACT_COMPLETE 
XTYP_UNREGISTER 


jmt | 
Specifies the format in which data is to be sent or received. 
hconv | | 
Identifies the conversation associated with the current transaction. 
hszl | 
Identifies a string. The meaning of this parameter depends on the type of the 
current transaction. For more information, see the description of the transaction _ 
type. | 
hsz2 
Identifies a string. The meaning of this parameter depends on the type of the 
current transaction. For more information, see the description of the transaction 


type. . 


~ Return Value 


Comments 


See Also 
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hData 
Identifies DDE data. The meaning of this parameter depends on the type of the 
current transaction. For more information, see the description of the transaction 
type. 

dwDatal 
Specifies transaction-specific data. For more jafonnstion: see the description of 
the transaction type. 


dwData2 | 
Specifies transaction-specific data. For more infonmanon: see the description of 
_ the transaction type. — | 


_ The return value depends on the transaction class. For more information about 


return values, see the descriptions of the individual DDE transactions in the 
Microsoft Windows Programmer’s Reference, Volume 3. 


The callback function is called asynchronously for transactions that do not involve 
creating or terminating conversations. An application that does not frequently ac- 
cept incoming messages will have reduced DDE performance because DDEML 
uses messages to initiate transactions. 


An application must register the callback function by specifying its address in a 
call to the Ddelnitialize function. DdeCallback is a placeholder for the applica- 
tion- or library-defined function name. The actual name must be exported by in- 
cluding it in an EXPORTS statement in the application’s module-definition file. 


DdeEnableCallback, Ddelnitialize 


DdeClientTransaction ogee ha 


#include <ddeml. h> 


HDDEDATA DdeClientTransaction(/pvData, cbData, hConv, hszItem, uF) mt, uType, uTimeout, 


lpuResult) 
void FAR* lpvData; 
DWORD cbData; 
~ HCONV hConv; 
HSZ hszltem; 
UINT uF mt; 
UINT uType; 
~DWORD uTimeout; 


_ /* address of data to pass to server — 7 
 /* length of data al 
_ /* handle of conversation =| eh, 
/* handle of item-name string =~ */ 
_/* clipboard data format : #} 
/* transaction type oe Sree a: 
/* timeout duration : | aah 


DWORD FAR? [puResult; op points to transaction result se 
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Parameters 


The DdeClientTransaction function begins a data transaction between a client 
and a server. Only a dynamic data exchange (DDE) client application can call this 
function, and only after establishing a conversation with the server. 


[pvData 
Points to the beginning of the data that the client needs to pass to the server. 


Optionally, an application can specify the data handle (HDDEDATA) to pass to 
the server, in which case the cbData parameter should be set to —1. This pa- 
rameter is required only if the uType parameter is XTYP_EXECUTE or 
XTYP_POKE. Otherwise, this parameter should be NULL. 


cbData 
Specifies the length, in bytes, of the data pointed to by the /pvData parameter. 
A value of —1 indicates that JpvData is a data handle that identifies the data 
being sent. 


hConv 
Identifies the conversation in which the transaction is to take place. 


hszItem 
Identifies the data item for which data is being exchanged during the transac- 
tion. This handle must have been created by a previous call to the DdeCreate- 
StringHandle function. This parameter is ignored (and should be set to NULL) 
if the uType parameter is XTYP_EXECUTE. 


uFmt 
Specifies the standard clipboard format in which the data item is being sub- 
mitted or requested. For more information about standard clipboard formats, 
see the Microsoft Windows Guide to Programming. 


ulype | 
Specifies the transaction type. This parameter can be one of the following 
values: 


Value Meaning 


XTYP_ADVSTART Begins an advise loop. Any number of distinct advise 
loops can exist within a conversation. An application 
can alter the advise loop type by combining the 
XTYP_ADVSTART transaction type with one or 
more of the following flags: 


Value Meaning 


XTYPF_NODATA Instructs the server to notify the 
| client of any data changes without 
actually sending the data. This 
flag gives the client the option of 
ignoring the notification or re- 
questing the changed data from 
the server. 


Return Value 


Errors 
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Value Meaning 


Value Meaning 


XTYPF_ACKREQ Instructs the server to wait until 
the client acknowledges that it re- 
ceived the previous data item 
before sending the next data item. 
This flag prevents a fast server 
from sending data faster than the 

client can process it. 


-XTYP_ADVSTOP Ends an advise loop. 


XTYP_EXECUTE Begins an execute transaction. 

XTYP_POKE Begins a poke transaction. 

XTYP_REQUEST Begins a request transaction. 
ulimeout — 


Specifies the maximum length of time, in milliseconds, that the client will wait _ 
for a response from the server application in a synchronous transaction. This pa- 
rameter should be set to TIMEOUT_ASYNC for asynchronous transactions. 


_ [puResult | 

Points to a variable that receives the result of the transaction. An application 
that does not check the result can set this value to NULL. For synchronous 
transactions, the low-order word of this variable will contain any applicable 
DDE_ flags resulting from the transaction. This provides support for applica- 
tions dependent on DDE_APPSTATUS bits. (It is recommended that applica- 
tions no longer use these bits because they may not be supported in future 
versions of the DDE Management Library.) For asynchronous transactions, this 
variable is filled with a unique transaction identifier for use with the Dde- 
AbandonTransaction function and the XTYP_XACT_ COMPLETE transac- 
tion. 


_ The return value is a data handle that identifies the data for successful syn- 


chronous transactions in which the client expects data from the server. The return 


value is TRUE for successful asynchronous transactions and for synchronous 
transactions in which the client does not expect data. The return value is FALSE 


for all unsuccessful transactions. 


Use the DdeGetLastError function to retrieve the error value, which may be one 


of the following: 


DMLERR _ADVACKTIMEOUT 


DMLERR_BUSY 
DMLERR_DATAACKTIMEOUT 
DMLERR_DLL_NOT_INITIALIZED 
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DMLERR_EXECACKTIMEOUT 
DMLERR_INVALIDPARAMETER 
DMLERR_MEMORY_ERROR > 
DMLERR_NO_CONV_ESTABLISHED 
DMLERR_NO_ERROR 
DMLERR_NOTPROCESSED 
DMLERR_POKEACKTIMEOUT 
DMLERR_POSTMSG_FAILED 
DMLERR_REENTRANCY 
DMLERR_SERVER_DIED 
DMLERR_UNADVACKTIMEOUT 


Comments When the application is finished using the data handle returned by the DdeClient- 
Transaction function, the application should free the handle by calling the Dde- 
FreeDataHandle function. 


Transactions can be synchronous or asynchronous. During a synchronous transac- 
tion, the DdeClientTransaction function does not return until the transaction 
completes successfully or fails. Synchronous transactions cause the client to enter 
a modal loop while waiting for various asynchronous events. Because of this, the 
client application can still respond to user input while waiting on a synchronous 
transaction but cannot begin a second synchronous transaction because of the ac- 
tivity associated with the first. The DdeClientTransaction function fails if any in- 
stance of the same task has a synchronous transaction already in progress. 


During an asynchronous transaction, the DdeClientTransaction function returns 
after the transaction is begun, passing a transaction identifier for reference. When 
the server’s DDE callback function finishes processing an asynchronous transac- 
tion, the system sends an XTYP_XACT_COMPLETE transaction to the client. 
This transaction provides the client with the results of the asynchronous transac- 
tion that it initiated by calling the DdeClientTransaction function. A client appli- 
cation can choose to abandon an asynchronous transaction by calling the 
DdeAbandonTransaction function. 


Example _ The following example requests an advise loop with a DDE server application: 


HCONV hconv; 
HSZ hszNow; 
HDDEDATA hData; 
DWORD dwResult; 
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hData = DdeClientTransaction( 
~(LPBYTE) NULL, /* pass no data to server */ 


Q, /* no data * / 
hconv, /* conversation handle ¥*/ 
hszNow, /* jtem name * / 
CE-TEXT, /* clipboard format * / 
XTYP_ADVSTART, /* start an advise loop~ #*/ 
1000, /* time-out in one second */ 
&dwResult); /* points to result flags */ 
See Also DdeAbandonTransaction, DdeAccessData, DdeConnect, DdeConnectList, 


-DdeCreateStringHandle 


DdeCmpStringHandles iat) 
#include <ddeml.h> 


int DdeCmpStringHandles(hsz/, hsz2) 
HSZ hsz1; /* handle of first string #/ 
HSZ hsz2; /* handle of second string i | 


The DdeCmpStringHandles function compares the values of two string handles. 
The value of a string handle is not related to the case of the associated string. 


Parameters hszl 
Specifies the first string handle. 


hsz2 
Specifies the second string handle. 


Return Value = —‘ The return value can be one of the following: 


Value Meaning 


-l.:: The value of hsz/ is either 0 or less than the value of hsz2. 
0 The values of hsz/ and hsz2 are equal (both can be 0). — 
i] _ The value of hsz2 is either 0 or less than the value of hszJ. 


Comments An application that needs to do a case-sensitive comparison of two string handles 
| should compare the string handles directly. An application should use DdeComp- 
StringHandles for all other comparisons to preserve the case- “Sensitive nature POF. 
dynamic data exchange (DDE). _ | 


160 DdeConnect 


Example 


See Also 


DdeConnect 


#include <ddeml.h> 


The DdeCompStringHandles function cannot be used to sort string handles al- 
phabetically. 


This example compares two service-name string handles and, if the handles are the 
Same, requests a conversation with the server, then issues an XTYP_ADVSTART 
transaction: 


HSZ hszClock; /* service name */ 


HSZ hszTime; /* topic name */ 

HSZ hszl; /* unknown server ok] 
HCONV hConv; /* conversation handle * / 
DWORD dwResult; /* result flags ** / 
DWORD idInst; /* instance identifier a / 
/* 


* Compare unknown service name handle with the string handle 
* for the clock application. 
* / 


if (1DdeCmpStringHandles(hsz1, hszClock)) { 


/* 

* If this is the clock application, start a conversation 
* with it and request an advise loop. 

* / 


hConv = DdeConnect(idInst, hszClock, hszTime, NULL); 
if (hConv != (HCONV) NULL) 
DdeClientTransaction(NULL, @, hConv, hszNow, 
CF_TEXT, XTYP_ADVSTART, 1000, &dwResult); 


DdeAccessData, DdeCreateStringHandle, DdeFreeStringHandle 


~HCONV DdeConnect(idinst, hszService, hszTopic, pCC) 


DWORD idinst; 
HSZ hszService; 
HSZ hszTopic; 


/* instance identifier **/ 
/* handle of service-name string ia) 
/* handle of topic-name string | 


CONVCONTEXT FAR* pCC; /* address of structure with context data —#/ 
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The DdeConnect function establishes a conversation with a server application that 
supports the specified service name and topic name pair. If more than one such 
server exists, the system selects only one. 


Parameters | idInst 
Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


hszService 
Identifies the string that specifies the service name of the server application 
with which a conversation is to be established. This handle must have been 
created by a previous call to the DdeCreateStringHandle function. If this pa- 
rameter is NULL, a conversation will be established with any available server. 


hszTopic 
Identifies the string that specifies the name of the topic on which a conversation 
is to be established. This handle must have been created by a previous call to 
the DdeCreateStringHandle function. If this parameter is NULL, a conversa- 
tion on any topic supported by the selected server will be established. 

pCC 
Points to tte CONVCONTEXT structure that contains conversation-context in- 
formation. If this parameter is NULL, the server receives the default CONV- 
CONTEXT structure during the XTYP_CONNECT or 
XTYP_WILDCONNECT transaction. 


The CONVCONTEXT structure has the following form: 


#Hinclude <ddeml1 .h> 


typedef struct WR ae { /* CC 2 / 
UINT cb; 
UINT wFlags; 
UINT wCountrylID; 
int j1CodePage; 
DWORD dwLangID; 
DWORD dwSecurity; 


} CONVCONTEXT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value — The return value is the handle of the established conversation if the function is. 
_ successful. Otherwise, it is NULL. | | 
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Errors 


| Comments 


Example 


See Also 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: | 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_CONV_ESTABLISHED 
DMLERR_NO_ERROR 


The client application should not make assumptions regarding which server will 
be selected. If an instance-specific name is specified in the hszService parameter, a 
conversation will be established only with the specified instance. Instance-specific 
service names are passed to an application’s dynamic data exchange callback func- 
tion during the XTYP_REGISTER and XTYP_UNREGISTER transactions. 


All members of the default CONVCONTEXT structure are set to zero except cb, 
which specifies the size of the structure, and iCodePage, which specifies 
CP_WINANSI (the default code page). 


The following example creates a service-name string handle and a topic-name 
string handle, then attempts to establish a conversation with a server that supports 
the service name and topic name. If the attempt fails, the example retrieves an 
error value identifying the reason for the failure. 


DWORD idInst = @L; 


— HSZ hszClock; 


HSZ hszTime; 
HCONV hconv; 
UINT uError; 


hszClock = DdeCreateStringHandle(idInst, "Clock", CP_WINANSI); 
hszTime = DdeCreateStringHandle(idiInst, "Time", CP_WINANSI); 


if ((hconv = DdeConnect( 


idInst, /* instance identifier ae / 
hszClock, /* server's service name x / 
hszTime, /* topic name * / 
NULL)) == NULL) { /* use default CONVCONTEXT * / 


uError = DdeGetLastError(idInst); 
} 


DdeConnectList, DdeCreateStringHandle, DdeDisconnect, 
yaer ounce Ddelnitialize 


DdeConnectList 163 


DdeConnectList 3.1 | 


#include <ddeml.h> 

HCONVLIST DdeConnectList(id/nst, hszService, hszTopic, hConvList, pCC) 

DWORD idinst; /* instance identifier */ 

HSZ hszService; /* handle of service-name string i) 

HSZ hszTopic; /* handle of topic-name string a 

HCONVLIST hConvList; /* handle of conversation list */ 

CONVCONTEXT FAR* pCC; /* address of structure with contextdata */ 
The DdeConnectList function establishes a conversation with all server applica- 
tions that support the specified service/topic name pair. An application can also 
use this function to enumerate a list of conversation handles by passing the func- 
tion an existing conversation handle. During enumeration, the Dynamic Data Ex- 
change Management Library (DDEML) removes the handles of any terminated 
conversations from the conversation list. The resulting conversation list contains 
the handles of all conversations currently established that support the specified 
service name and topic name. 

Parameters idInst 


Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. | 


hszService 
Identifies the string that specifies the service name of the server application 
with which a conversation is to be established. If this parameter is NULL, the 
system will attempt to establish conversations with all available servers that sup- 
port the specified topic name. | 


hszTopic 
Identifies the string that specifies the name of the topic on which a conversation 
is to be established. This handle must have been created by a previous call to 
the DdeCreateStringHandle function. If this parameter is NULL, the system 
will attempt to establish conversations on all topics supported by the selected 
server (or servers). 


hConvList 


Identifies the conversation list to be enumerated. This parameter should be set 
to NULL if a new conversation list is to be established. 
pCc | | 
~ Points to the CONVCONTEXT structure that contains conversation-context 
information. If this parameter is NULL, the server receives the default 
CONVCONTEXT structure during the XTYP_CONNECT or 
XTYP_WILDCONNECT transaction. 


The CONVCONTEXT structure has the following form: 
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Return Value 


Errors 


~ Comments 


Example 


d#Finclude <ddem].h> 


typedef struct tagCONVCONTEXT { /* cc 2 * / 
‘ UINT — cb; 

UINT wFlags; 

UINT wCountryID; 

int iCodePage; 

DWORD dwLangID; 

DWORD dwSecurity; 


} CONVCONTEXT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the handle of a new conversation list if the function is success- 
ful. Otherwise, it is NULL. The handle of the old conversation list is no longer 
valid. © 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALID_PARAMETER 
DMLERR_NO_CONV_ESTABLISHED 
DMLERR_NO_ERROR 
DMLERR_SYS_ERROR 


An application must free the conversation-list handle returned by this function, re- 
gardless of whether any conversation handles within the list are active. To free the 
handle, an application can call the DdeDisconnectList function. 


All members of the default CONVCONTEXT structure are set to zero except cb, 
which specifies the size of the structure, and iCodePage, which specifies 
CP_WINANSI (the default code page). 


The following example uses the DdeConnectList function to establish a conversa- 
tion with all servers that support the System topic, counts the servers, allocates a 
buffer for storing the server’s service-name string handles, and then copies the han- 
dles to the buffer: | 


See Also 


HCONVLIST hconvList; /* 
DWORD idInst; /* 
HSZ hszSystem; /* 
HCONV hconv = NULL; /* 
CONVINFO ci; /* 


UINT cConv = @; x 
HSZ *pHsz, *aHsz; /* 


conversation list * / 
instance identifier * / 
System topic * / 
conversation handle * / 


holds conversation data */ 
count of conv. handles */ 
point to string handles */ 


DdeConnectList 


/* Connect to all servers that support the System topic. */ 


hconvList = DdeConnectLi 
(HCONV) NULL, (LPVOI 


st(idInst, (HSZ) NULL, hszSystem, 


D) NULL); 


/* Count the number of handles in the conversation list. */ 


while ((hconv = DdeQueryNextServer(hconvList, hconv)) 


cConv++; 


hconv = (HCONV) NULL; 


aHsz = (HSZ *) LocalAlloc(LMEM FIXED, 


/* Copy the string handl 


pHsz = aHsz; 


while ((hconv = DdeQueryNextServer(hconvList, hconv)) 


DdeKeepStringHand] e( 


om Allocate a buffer for the string handles. */ 


es to the buffer. */ 


idInst, ci.hszSvcPartner) ; 


*DHSZ++ = ci.hszSvcPartner; 


. /* Use the handles; converse with servers. */ 


/* Free the memory and terminate conversations. */ 


LocalFree( (HANDLE) aHsz); 
DdeDisconnectList(hconvList) ; 


DdeConneect DdeCreateStringHandle, DdeDisconnect, seine wont asmas 


Ddelnitialize, DdeQueryNextServer 


l= (HCONV) NULL) 


cConv * sizeof (HSZ)); 
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l= (HCONV) NULL) { 
DdeQueryConviInfo(hconv, QID_SYNC, (PCONVINFO) &ci); 
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DdeCreateDataHandle ee Exm 


#include <ddeml. h> 


HDDEDATA DdeCreateDataHandle(idinst, IpvSreBuf, cbinitData, offS td hocitene ul'mt, afCmd) 
DWORD idinst; /* instance identifier 


void FAR®* [pvSrcBuf; /* address of source buffer a 
DWORD cbinitData; /* jength of global memory object | | 
DWORD offSrcBuf; _/* offset from beginning of source buffer */ 
HSZ hszlItem; /* handle of item-name string */ 
— UINT uF mt; /* clipboard data format */ 
UINT afCmd; /* creation flags */ 


The DdeCreateDataHandle function creates a global memory object and fills the 
object with the data pointed to by the [pvSrcBuf parameter. A dynamic data ex- 
change (DDE) application uses this function during transactions that involve pass- 
ing data to the partner application. 


Parameters idInst 
Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


[pvSrcBuf 
Points to a buffer that contains data to be copied to the global memory object. If. 
this parameter is NULL, no data is copied to the object. 


cbInitData 
Specifies the amount, in bytes, of memory to allocate for the global memory ob- 
ject. If this parameter is zero, the [pvSrcBuf parameter is ignored. 


offSrcBuf 
Specifies an offset, in bytes, from the beginning of the buffer pointed to " the 
[pvSrcBuf parameter. The data poe at this offset is copied from the buffer 
to the global memory object. 


hszltem 
Identifies the string that specifies the data item corresponding to the global 
memory object. This handle must have been created by a previous call to the 
DdeCreateStringHandle function. If the data handle is to be used in an 
XTYP_EXECUTE transaction, this parameter must ve set to NULL. 


uFmt 
Specifies the standard clipboard format of the data. 


afCmd 
Specifies the creation flags. This parameter can be HDATA_APPOWNED, 
which specifies that the server application that calls the DdeCreate- 
DataHandle function will own the data handle that this function creates. This 
makes it possible for the server to share the data handle with multiple clients in- 
stead of creating a separate handle for each request. If this flag is set, the server 


Return Value 


Errors 


Comments 


Example 
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must eventually free the shared memory object associated with this handle by 
using the DdeFreeDataHandle function. If this flag is not set, after the data 
handle is returned by the server’s DDE callback function or used as a parameter 
in another DDE Management Library function, the handle becomes invalid in 
the application that creates the handle. 


The return value is a data handle if the function is successful. Otherwise, it is 
NULL. | 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_MEMORY_ERROR 
DMLERR_NO_ERROR 


Any locations in the global memory object that are not filled are undefined. — 


After a data handle has been used as a parameter in another DDEML function or 
has been returned by a DDE callback function, the handle may be used only for 


read access to the global memory object identified by the handle. 


If the application will be adding data to the global memory object (using the 
DdeAddData function) so that the object exceeds 64K in length, then the applica- 
tion should specify a total length (cbInitData + offSrcData) that is equal to the an- 
ticipated maximum length of the object. This avoids unnecessary data copying and 
memory reallocation by the system. 


The following example processes the XTYP_WILDCONNECT transaction by re-_ 
turning a data handle to an array of HSZPAIR structures—one for each topic 
name supported: 


i#tdefine CTOPICS 2 


UINT type; 

UINT fmt; 

HSZPAIR ahpL(CTOPICS + 1)]; 
HSZ ahszTopicList[CTOPICS]; 
HSZ hszServ, hszTopic; 

WORD i, j; 


if (type == XTYP_WILDCONNECT) { 


/* | : | 

* Scan the topic list and create array of HSZPAIR data 
* structures. _ | 
ey 
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See Also 


DdeCreateStringHandle 


#include <ddeml.h> 


j = 4; | 
for (i = @; i < CTOPICS; i++) { 
if (hszTopic == (HSZ) NULL || 
—  hszTopic == ahszTopicLlist[i]) { 
ahp[j].hszSvc = hszServ; 
ahp[j++].hszTopic = ahszTopicList[i]; 


} 


/* 

* End the list with an HSZPAIR structure that contains NULL 
* string handles as its members. 

* / 


ahp[j].hszSvc = NULL; 
ahp[jt+].hszTopic = NULL; 


/* 
* Return a handle to a global memory acu containing the 
* HSZPAIR structures. 


* / 

return DdeCreateDataHand1e( 
idInst, /* instance identifier a / 
—gahp, _/* points to HSZPAIR array */ 
sizeof(HSZ) * j, /* length of the array * / 
Q, | /* start at the beginning */ 
NULL, /* no item-name string * / 
fmt, /* return the same format */ 
Q); /* Jet the system own it * / 


- DdeAccessData, DdeFreeDataHandle, DdeGetData, Ddelnitialize 


~ HSZ DdeCreateStringHandle(idinst, lpszString, codepage) 


DWORD idinst; 
LPCSTR IpszString; 
int codepage; 


/* instance identifier st 
/* address of null-terminated string */ 
/* code page **/ 


The DdeCreateStringHandle function creates a handle that identifies the string 
pointed to by the /pszString parameter. A dynamic data exchange (DDE) client or 
server application can pass the string handle as a parameter to other DDE Manage- 
ment Library functions. 


Parameters 


Return Value 


Errors 


Comments 
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idInst 
Specifies the application-instance identifier obtained by a previous call to the 
DdelInitialize function. 


[pszString 
Points to a buffer that contains the null-terminated string for which a handle is 
to be created. This string may be any length. 


codepage 
Specifies the code page used to render the string. This value should be either 
CP_WINANSI or the value returned by the GetKBCodePage function. A 
value of zero implies CP_WINANSI. 


The return value is a string handle if the function is successful. Otherwise, it is 
NULL. 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 
DMLERR_SYS_ERROR 


Two identical strings always correspond to the same string handle. String handles 
are unique across all tasks that use the DDEML. That is, when an application 
creates a handle for a string and another application creates a handle for an identi- 
cal string, the string handles returned to both applications are identical—regardless 
of case. 


The value of a string handle is not related to the case of the string it identifies. 


When an application has either created a string handle or received one in the call- 
back function and has used the DdeKeepStringHandle function to keep it, the ap- 
plication must free that string handle when it is no longer needed. 


An instance-specific string handle is not mappable from string handle to string | 
to string handle again. This is shown in the following example, in which the 
DdeQueryString function creates a string from a string handle and then 
DdeCreateStringHandle creates a string handle from that string, but the 

two handles are not the same: 


DWORD idInst; 

DWORD cb; 

HSZ hszInst, hszNew; 
PSZ pszInst; 


DdeQueryString(idInst, hszInst, pszInst, cb, CP_WINANSI); 
hszNew = ee re pszInst, CP_WINANSI); 
/* hszNew l= hszInst ! */ 
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Example 


See Also 


DdeDisconnect 


#include <ddeml.h> 


_ The following example creates a service-name string handle and a topic-name 


string handle and then attempts to establish a conversation with a server that sup- 
ports the service name and topic name. If the attempt fails, the example obtains an 
error value identifying the reason for the failure. 


DWORD idInst = @L; 
HSZ hszClock; 

HSZ hszTime; 

HCONV hconv; 

UINT uError; 


hszClock = DdeCreateStringHandle(idInst, "Clock", CP_WINANSI); 
hszlime = DdeCreateStringHandle(idInst, "Time", CP_WINANSI); 


if ((hconv = DdeConnect( 


idInst, /* instance identifier a / 
hszClock, /* server's service name | * / 
hszTime, | /* topic name a / 
NULL)) == NULL) { /* use default CONVCONTEXT * / 


uError = DdeGetLastError(idInst); 


DdeAccessData, DdeCmpStringHandles, DdeF reeStringHandle, 
Ddelnitialize, DdeKeepStringHandle, DdeQueryString 


BOOL DdeDisconnect(hConv) 


HCONV hConv; 


Parameters 


Return Value 


Errors 


/* handle of conversation */ 


The DdeDisconnect function terminates a conversation started by either the Dde- 
Connect or DdeConnectList function and invalidates the given conversation | 
handle. | 


hConv 
Identifies the active conversation to be terminated. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one 


of the following: 


Comments 


See Also. 


DdeDisconnectList 


#include <ddeml.h> 
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DMLERR_DLL_NOT_INITIALIZED 


~ DMLERR_NO_CONV_ESTABLISHED 


DMLERR_NO_ERROR 


Any incomplete transactions started before calling DdeDisconnect are immedi- 
ately abandoned. The XTYP_DISCONNECT transaction type is sent to the dy- 
namic data exchange (DDE) callback function of the partner in the conversation. 
Generally, only client applications need to terminate conversations. 


DdeConnect, DdeConnectList, DdeDisconnectList 


| BOOL DdeDisconnectList(iConvList) | 
~ HCONVLIST hConvList; —/* handle of conversation list ¥/ 


Parameters 
Return Value 


Errors 


Comments 


See Also 


The DdeDisconnectList function destroys the given conversation list and termi- 
nates all conversations associated with the list. 


hConvList oe 
Identifies the conversation list. This handle must have been created sy a pre- 


vious call to the DdeConnectList function. 


The return value is nonzero if the function is successful. Otherwise, it 1s Zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one 


of the following: 


- DMLERR_DLL_NOT_INITIALIZED > 


DMLERR_INVALIDPARAMETER 


| ee 


An application can use the DdeDisconnect function to terminate individual c con- 


versations in 1 the list. 


DdeConnect, DdeConnectList, DdeDisconnect 
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DdeEnableCallback 


#include <ddeml.h> 


BOOL DdeEnableCallback(id/nst, hConv, uCmd) 


DWORD idinst; 
HCONV hConv; 
UINT uCmd; 


Parameters 


Return Value 


/* instance identifier **/ 
/* handle of conversation | 
/* the enable/disable function code * / 


The DdeEnableCallback function enables or disables transactions for a specific 
conversation or for all conversations that the calling application currently has es- 
tablished. 


After disabling transactions for a conversation, the system places the transactions 
for that conversation in a transaction queue associated with the application. The ap- 
plication should reenable the conversation as soon as possible to avoid losing 
queued transactions. 


idInst 
Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


hConv | 
Identifies the conversation to enable or disable. If this parameter is NULL, the 
function affects all conversations. 


uCmd 
Specifies the function code. This parameter can be one of the following values: 


Value Meaning 


EC_ENABLEALL Enables all transactions for the specified conversation. 
EC_ENABLEONE Enables one transaction for the specified conversation. 
EC_DISABLE Disables all blockable transactions for the specified conver- 

sation. . 

A server application can disable the following transactions: 

XTYP_ADVSTART 

XTYP_ADVSTOP 

XTYP_EXECUTE 

XTYP_POKE 

XTYP_REQUEST | 

A client application can disable the following transactions: 

XTYP_ADVDATA 

_~XTYP_XACT_COMPLETE 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


~ Errors 


Comments 


See Also 
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Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 7 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_NO_ERROR 
DMLERR_INVALIDPARAMETER 


An application can disable transactions for a specific conversation by returning 
CBR_BLOCK from its dynamic data exchange (DDE) callback function. When 
the conversation is reenabled by using the DdeEnableCallback function, the sys- 


_ tem generates the same transaction as was in process when the conversation was 


disabled. 


~ DdeConnect, DdeConnectList, DdeDisconnect, Ddelnitialize 


DdeFreeDataHandle ee ee 


#include <ddeml.h> 


BOOL DdeF reeDataHandle(hData) 


HDDEDATA hData; 


Parameters 


Return Value 


Errors 


‘Comments 


/* handle of global n memory object —_ */ 


The DdeFreeDataHandle function frees a global ely she and deletes the 


data handle associated with the object. 


hData 


Identifies the global m memory object to be freed. This handle must have been 
created by a previous call to the DdeCreateDataHandle function or returned 
by the DdeClientTransaction function. 


The return value is nonzero if the function is successful. MCT it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be ¢ one 
of the following: 


DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 
An application must call DdeFreeDataHandle under the following circumstances: 


= To free a global memory object that the application allocated by calling the 
DdeCreateDataHandle function if the object’s data handle was never passed _ 
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by the application to another Dynamic Data Exchange Management Library 
(DDEML) function 


= To free a global memory object that the application allocated by specifying the 
HDATA_APPOWNED flag in a call to the DdeCreateDataHandle function 


= To free a global memory object whose handle the application received from the 
DdeClientTransaction function 


The system automatically frees an unowned object when its handle is returned by 
a dynamic data exchange (DDE) callback function or used as a parameter in a 
DDEML function. 


Example | The following example creates a global memory object containing help informa- 
tion, then frees the object after passing the object’s handle to the client application: 


DWORD idInst; 
HSZ hszItem; . 
HDDEDATA hDataHelp; 


char szDdeHelp[] = "DDEML test server help:\r\n"\ 
"\tThe ‘Server’ (service) and 'Test' (topic) names may change.\r\n"\ 
"Items supported under the ‘Test" topic are:\r\n"\ 
"\tCount:\tThis value increments on each data change.\r\n"\ 
"\tRand:\tThis value is changed after each data change. \r\n"\ 
"\t\tIn Runaway mode, the above items change after a request.\r\n"\ 
"\tHuge:\tThis is randomly generated text data >64k that the\r\n"\ 
"\t\ttest client can verify. It is recalculated on each\r\n"\ 
"\t\trequest. This also verifies huge data poked or executed\r\n"\ 
"\t\tfrom the test client.\r\n"\ , / 
"\tHelp:\tThis help information. This data is APPOWNED.\r\n"; 


/* Create global memory object containing help information. */ 
if (!hDataHelp) { 


hDataHelp = DdeCreateDataHandle(idInst, szDdeHelp, 
strlen(szDdeHelp) + 1, @, hszItem, CF_TEXT, HDATA_APPOWNED) ; 


. /* Pass help information to client application. */ 


/* Free the global memory object. */ 


if (hDataHelp) 
DdeFreeDataHandle(hDataHelp) ; 


See Also | DdeAccessData, DdeCreateDataHandle 
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DdeFreeStringHandle | [ 3.1 | 


_#include <ddeml.h> 


BOOL DdeFreeStringHandle(id/nst, hsz) 
DWORD idlnst; /* instance identifier a) 


HSZ hsz; /* handle of string */ 
The DdeFreeStringHandle function frees a string handle in the calling applica- 
tion. 

Parameters idInst 


Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


hsz 
Identifies the string handle to be freed. This handle must have been created By a 
previous call to the Pes renee eran function. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments An application can free string handles that it creates with the DdeCreateString- 
Handle function but should not free those that the system passed to the applica- 
tion’s dynamic data exchange (DDE) callback function or those returned in the ~ 
CONVINFO structure by the DdeQueryConvinfo function. 


Example _ The following example frees string handles during the XTYP_DISCONNECT 
| transaction: 


DWORD idInst = @L; 
HSZ hszClock; 

HSZ hszTime; 

HSZ hszNow; 

UINT type; 


if (type == XTYP_DISCONNECT) { 
- DdeFreeStringHandle(idIinst, hszClock);. 
DdeFreeStringHandle(idInst, hszTime); 
DdeFreeStringHandle(idinst, hsZNow) ; 


“return (HODEDATA) NULL; 
i 


See Also , DdeCmpStringHandles, DdeCreateStringHandle. Ddetnitialize 
oe an paeKecpsemenan Dae 
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DdeGetData 


#include <ddeml.h> 


DWORD DdeGetData(hData, pDest, cbMax, offSrc) 


HDDEDATA /hData; 
void FAR* pDest; 
DWORD cbhMax; 
DWORD offSrc; 


Parameters 


Return Value 


Errors 


Example 


/* handle of global memory object */ 


/* address of destination buffer */ 
/* amount of data to copy =] 
/* offset to beginning of data =] 


The DdeGetData function copies data from the ENan global memory object to the 
specified local buffer. 


hData 
Identifies the global memory object that contains the data to copy. 


pDest 
Points to the buffer that receives the data. If this parameter is NULL, the 
DdeGetData function returns the amount, in bytes, of data that would be 
copied to the buffer. 


cbMax | 
Specifies the maximum amount, in bytes, of data to copy to the buffer pointed 
to by the pDest parameter. Typically, this parameter specifies the length of the 
buffer pointed to by pDest. 


offSrc 
Specifies an offset within the global memory sieds Data is Opie from me ob- 
ject beginning at this offset. 


If the pDest parameter points to a buffer, the return value is the size, in bytes, of 
the memory object associated with the data handle or the size specified in the 
cbMax parameter, whichever is lower. 


If the pDest parameter is NULL, the return value is the size, in bytes, of the 
memory object associated with the data handle. 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALID_HDDEDATA 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 


The following example copies data from a global memory object to a local buffer 
and then fills the TIME structure with data from the buffer: 


See Also 
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HDDEDATA hData; 
char szBuf[32]; 


typedef struct { 
int hour; 
int minute; 
int second; 
} TIME; 


DdeGetData(hData, (LPBYTE) szBuf, 32L, QL); 


sscanf(szBuf, "%d:%d:%d", &nTime.hour, &nTime.minute, 
&nTime.second); 


DdeAccessData, DdeCreateDataHandle, DdeFreeDataHandle 


DdeGetLastError fs BA 


-#include <ddeml. h> 


UINT DdeGetLastError(idinst) : 


DWORD idinst; 


Parameters 


Return Value 


/* instance identifier  _*/ 


The DdeGetLastError function returns the most recent error value set by the 
failure of a Dynamic Data Exchange Management Library (DDEML) function and 


resets the error value to DMLERR_NO_ERROR. 


idinst 


Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


The return value i is the last error value. Following are the possible DDEML error 


values: 
Value : Meaning | | 
~ DMLERR_ADVACKTIMEOUT A request for a synchronous advise trans- 
| | | action has timed out. | 
DMLERR_BUSY | -_ The response to the transaction oaiced 
| | | the DDE_FBUSY bit to be set. _ : 
DMLERR_DATAACK TIMEOUT A request for a synchronous data transac- 


tion has timed out. 


Value 


DMLERR_DLL_NOT_INITIALIZED 


DMLERR_DLL_USAGE 


DMLERR_EXECACKTIMEOUT 


DMLERR_INVALIDPARAMETER 


DMLERR_LOW_ MEMORY 


DMLERR_MEMORY_ERROR 
DMLERR_NO_CONV_ESTABLISHED 


DMLERR_NOTPROCESSED 
DMLERR_POKEACKTIMEOUT 


DMLERR_POSTMSG_FAILED 


DdeGetLastError 


Meaning 


A DDEML function was called without 
first calling the DdelInitialize function, 
or an invalid instance identifier was 
passed to a DDEML function. 


An application initialized as 
APPCLASS_MONITOR has attempted 
to perform a DDE transaction, or 

an application initialized as 
APPCMD_CLIENTONLY has 
attempted to perform server transactions. 


A request for a synchronous execute 
transaction has timed out. 


A parameter failed to be validated by the 
DDEML. Some of the possible causes 
are as follows: 


=" The application used a data handle ini- 
tialized with a different item-name 
handle than that required by the trans- 
action. 


= The application used a data handle that 
was initialized with a different clip- 
board data format than that required by 
the transaction. 


= The application used a client-side con- 
versation handle with a server-side 
function or vise versa. 


=" The application used a freed data 
handle or string handle. 


=" More than one instance of the applica- 
tion used the same object. 


A DDEML application has created a pro- 
longed race condition (where the server 
application outruns the client), causing 
large amounts of memory to be con- 
sumed. 


A memory allocation failed. 


A client’s attempt to establish a conversa- 
tion has failed. 


A transaction failed. 


A request for a synchronous poke transac-_ 
tion has timed out. 


An internal call to the PostMessage func- 
tion has failed. 


Example 


DdeGetLastError 


Value | Meaning 


DMLERR_REENTRANCY An application instance with a syn- 
chronous transaction already in progress 
attempted to initiate another synchronous 
transaction, or the DdeEnableCallback | 
function was called from within a 

| DDEML callback function. 

DMLERR_SERVER_DIED A server-side transaction was attempted 
on a conversation that was terminated by 
the client, or the server terminated before 
completing a transaction. 


DMLERR._SYS_ ERROR An internal error has occurred in the 


DDEML. 
DMLERR_UNADVACKTIMEOUT A request to end an advise transaction 

has timed out. | | 
DMLERR_UNFOUND_QUEUE_ID An invalid transaction identifier was 


passed to a DDEML function. Once the 
application has returned from an 
XTYP_XACT_COMPLETE callback, 
the transaction identifier for that callback 
is no longer valid. | 
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The following example calls the DdeGetLastError function if the DdeCreate- | 


DataHandle function fails: 


DWORD idInst; 

HDDEDATA hddeMyData; 
HSZPAIR ahszp[2]; 

HSZ hszClock, hszTime; 


/* Create string handles. */ 

hszClock = DdeCreateStringHandle(idInst, (LPSTR) "Clock", 
CP_WINANSI); — 

hszTime = DdeCreateStringHandle(idInst, (LPSTR) "Time", 
CP_WINANSI); 


/* Copy handles to an HSZPAIR structure. */ 


ahszp[@].hszSvc = hszClock; 
ahszp[@].hszTopic = hszTime; 
ahszpLl].hszSvc = (HSZ) NULL; 
ahszpL1].hszTopic = (HSZ) NULL; 


/* Create a global memory object. */ 


hddeMyData = DdeCreateDataHandle(idInst, ahszp, 
| sizeof(ahszp), @, NULL, CF_TEXT, @); . 
if (hddeMyData == NULL) | 
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See Also 


Ddelnitialize 


/* | 

* Pass error value to application-defined error handling 
* function. 

* / 


HandleError(DdeGetLastError(idInst)); 


Ddelnitialize 


#include <ddeml.h> 

UINT Ddelnitialize(/pidinst, pfnCallback, afCmd, uRes) 

DWORD FAR? IpidInst; /* address of instance identifier */ 
PFNCALLBACK pfnCallback; /* address of callback function **/ 
DWORD afCmd; /* array of command and filter flags **/ 
DWORD uRes; /* reserved */ 


Parameters 


The Ddelnitialize function registers an application with the Dynamic Data Ex- 


change Management Library (DDEML). An application must call this function 


before calling any other DDEML function. 


lpidInst 
Points to the application-instance identifier. At initialization, this parameter 
should point to OL. If the function is successful, this parameter points to the in- 
stance identifier for the application. This value should be passed as the idInst 
parameter in all other DDEML functions that require it. If an application uses 
multiple instances of the DDEML dynamic link library, the application should 
provide a different callback function for each instance. 


If [pidInst points to a nonzero value, this implies a reinitialization of the 
DDEML. In this case, /pidInst must point to a valid application-instance identi- 
fier. 


| pfnCallback 


Points to the application-defined DDE callback function. This function 
processes DDE transactions sent by the system. For more information, see the 
description of the DdeCallback callback function. | 

afCmd | } 
Specifies an array of APPCMD_ and CBF_ flags. The APPCMD_ flags pro- — 
vide special instructions to the DdelInitialize function. The CBF_ flags set fil- 
ters that prevent specific types of transactions from reaching the callback 
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function. Using these flags enhances the performance of a DDE application by 
eliminating unnecessary calls to the callback function. 


This parameter can be a combination of the following flags: 
Flag Meaning 


APPCLASS_MONITOR Makes it possible for the application to 
monitor DDE activity in the system. This 
flag is for use by DDE monitoring appli- 
cations. The application specifies the 

_ types of DDE activity to monitor by com- 
bining one or more monitor flags with 
the APPCLASS_MONITOR flag. For 
details, see the following Comments sec- 


tion. 
APPCLASS_STANDARD Registers the application as a standard — 
(nonmonitoring) DDEML application. 
APPCMD_CLIENTONLY Prevents the application from becoming — 


a server in a DDE conversation. The ap- 
plication can be only a client. This flag 
reduces resource consumption by the 
DDEML. It includes the functionality of 
the CBF_FAIL_ALLSVRXACTIONS 
flag. 

APPCMD_FILTERINITS | Prevents the DDEML from. 
sending XTYP_CONNECT and 
XTYP_WILDCONNECT transactions to 
the application until the application has 
created its string handles and registered 
its service names or has turned off 
filtering by a subsequent call to the 
DdeNameService or Ddelnitialize func- 
tion. This flag is always in effect when 
an application calls DdeInitialize for the 
first time, regardless of whether the appli- 
cation specifies this flag. On subsequent 
calls to Ddelnitialize, not specifying this 
flag turns off the application’s service- 
name filters; specifying this flag turns on 

the application’s service-name filters. 


CBF_FAIL_ALLSVRXACTIONS Prevents the callback function from re- 
| ceiving server transactions. The system 
will return DDE_FNOTPROCESSED to 
each client that sends a transaction to this 
application. This flag is equivalent to 
combining all CBF_FAIL_ flags. 
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Flag 
CBF_FAIL_ADVISES 


CBF_FAIL_CONNECTIONS 


CBF_FAIL_EXECUTES 


CBF_FAIL_POKES 


CBF_FAIL_REQUESTS 


CBF_FAIL_SELFCONNECTIONS 


_ CBF_SKIP_ALLNOTIFICATIONS 


CBF _SKIP_CONNECT CONFIRMS 


Meaning 


Prevents the callback function from 
receiving XTYP_ADVSTART and 
XTYP_ADVSTOFP transactions. 

The system will return 
DDE_FNOTPROCESSED to each client 
that sends an XTYP_ADVSTART or 
XTYP_ADVSTOP transaction to the 
server. | 


Prevents the callback function from 
receiving XTYP_CONNECT and 
XTYP_WILDCONNECT transactions. 


Prevents the callback function 

from receiving XTYP_EXECUTE 
transactions. The system will return 
DDE_FNOTPROCESSED to a client 
that sends an XTYP_EXECUTE transac- 
tion to the server. 


Prevents the callback function from 
receiving XTYP_POKE trans- 

actions. The system will return 
DDE_FNOTPROCESSED to a client 
that sends an XTYP_POKE transaction 
to the server. 


Prevents the callback function 

from receiving XTYP_REQUEST 
transactions. The system will return 
DDE_FNOTPROCESSED to a client 
that sends an XTYP_REQUEST transac- 
tion to the server. 


Prevents the callback function from re- 
ceiving XTYP_CONNECT transactions 
from the application’s own instance. This 
prevents an application from establishing 
a DDE conversation with its own in- 
stance. An application should use this 
flag if it needs to communicate with 
other instances of itself but not with it- 
self. 


Prevents the callback function from re- 
ceiving any notifications. This flag is 
equivalent combining all CBF_SKIP_ 
flags. ) 


Prevents the callback function from re- 
ceiving XTYP_CONNECT_CONFIRM 


— notifications. 


Return Value 


Comments 
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Flag | Meaning 

CBF _SKIP_ DISCONNECTS Prevents the callback function from re- 
ceiving XTYP DISCONNECT notifica- 
tions. 

CBF SKIP REGISTRATIONS Prevents the callback function from re- 

| ceiving XTYP_REGISTER notifications. 

CBF_SKIP_UNREGISTRATIONS Prevents the callback function from re- 
ceiving XTYP_UNREGISTER notifica- 
tions. 

uRes 


Reserved; must be set to OL. 


| The return value is one of the following: 


DMLERR_DLL_USAGE 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 
DMLERR_SYS_ERROR 


An application that uses multiple instances of the DDEML must not pass DDEML 
objects between instances. 


A DDE monitoring application should not attempt to perform DDE (establish con- 
versations, issue transactions, and so on) within the « context of the same applica- 
tion instance. 3 


A synchronous transaction will fail with a DMLERR_REENTRANCY error if any 
instance of the same task has a synchronous transaction already in progress. 


A DDE monitoring application can combine one or more of the following monitor 
flags with the APPCLASS_MONITOR flag to specify the types of DDE activity 


to monitor: 


Flag Meaning 


MF_CALLBACKS __ Notifies the callback function whenever a transaction is sent to 
any DDE callback function in the system. 


MF_CONV Notifies the callback function whenever a conversation is estab- 
lished or terminated. 

MF_ ERRORS Notifies the callback function whenever a DDE error occurs. 

MF_HSZ_INFO — Notifies the callback function whenever a DDE application 


creates, frees, or increments the use count of a string handle or 
whenever a string handle is freed as a result of a call to the 
DdeUninitialize function. 
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Flag | Meaning : . 
MF_LINKS Notifies the callback function whenever an advise loop is 
| started or ended. 
MF_POSTMSGS Notifies the callback function whenever the system or an appli- 


cation posts a DDE message. 


MF_SENDMSGS Notifies the callback function whenever the system or an appli- 


Example 


See Also 


DdeKeepStringHandle 


#include <ddeml.h> 


cation sends a DDE message. 


The following example obtains a procedure-instance address for a DDE callback 
function, then initializes the application with the DDEML. 


DWORD idInst = @L; 
FARPROC 1pDdeProc; 


lpDdeProc = MakeProcInstance((FARPROC) DDECallback, hInst); 
if (DdeInitialize((LPDWORD) &idInst, (PFNCALLBACK) lpDdeProc, 
| APPCMD_CLIENTONLY, @L)) 
return FALSE; 


DdeClientTransaction, DdeConnect, DdeCreateDataHandle, DdeEnable- 
Callback, DdeNameService, DdePostAdvise, DdeUninitialize 


BOOL DdeKeepStringHandle(idinst, hsz) 


DWORD idinst; 
HSZ hsz; 


Parameters | 


/* instance identifier */ 
/* handle of string” et 


The DdeKeepStringHandle function increments the usage count (increases it by 
one) associated with the given handle. This function makes it possible for an appli- 
cation to save a string handle that was passed to the application’s dynamic data ex- 
change (DDE) callback function. Otherwise, a string handle passed to the callback 
function is deleted when the callback function returns. 


idmst ase | | : 
Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 

hsz | | 
Identifies the string handle to be saved. 
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ReturnValue § —S—“ The return value is nonzero if the function is successful. Otherwise, it is zero. 
Example The following example is a portion of a DDE callback function that increases the 
| usage count and saves a local copy of two string handles: 
HSZ hszl; 
HSZ hsz2; 


static HSZ hszServerBase; 

static HSZ hszServerlInst; 

DWORD idInst; 

case XTYP_REGISTER: 
/* Keep the handles for later use. */ 
DdeKeepStringHandle(idInst, hsz1); 
DdeKeepStringHandle(idInst, hsz2); 
hszServerBase = hszl; 
hszServerInst = hsz2; 


. /* Finish processing the transaction. */ 


See Also DdeCreateStringHandle, DdeFreeStringHandle, Ddelnitialize, 
3 DdeQueryString | 


DdeNameService faa 
| #include <ddeml.h> | 


HDDEDATA DdeNameService(idinst, hszl, hszRes, ne 
DWORD idlnst; /* instance identifier 


HSZ hsz1; /* handle of service-name string M 
HSZ hszRes; | /* reserved — */ 
—UINT afCmd; /* service-name flags a 


The DdeNameService function registers or unregisters the service names that a 
dynamic data exchange (DDE) server supports. This function causes the system to 
send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running 
DDE Management Library (DDEML) client applications. 


A server application should call this function to register each service name that it 
supports and to unregister names that it previously registered but no longer sup- 
ports. A server should also call this function to upree eet its service names just © 
before terminating. 3 
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Parameters 


Return Value 


Errors 


Comments 


idInst 
Specifies the application-instance identifier obtained iby a previous call to the 
Ddelnitialize function. 


hszl 
Identifies the string that specifies the service name that the server is registering 
or unregistering. An application that is unregistering all of its service names 
should set this parameter to NULL. 


hszRes 
Reserved; should be set to NULL. 


afCmd 
Specifies the service-name flags. This parameter can be one of the following 
values: 


Value Meaning 


DNS_REGISTER Registers the given service name. 

DNS_UNREGISTER Unregisters the given service name. If the hsz/ parameter 
is NULL, all service names registered by the server will 
be unregistered. 

DNS_FILTERON Turns on service-name initiation filtering. This filter pre- 
vents a server from receiving XTYP_CONNECT transac- 
tions for service names that it has not registered. This is 
the default setting for this filter. 

If a server application does not register any 
service names, the application cannot receive 
XTYP_WILDCONNECT transactions. 

DNS_FILTEROFF Turns off service-name initiation filtering. If this flag is 
set, the server will receive an XTYP_CONNECT transac- 
tion whenever another DDE application calls the Dde- 
Connect function, regardless of the service name. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one | 
of the following: | 


DMLERR_DLL_NOT_INITIALIZED 


~ DMLERR_DLL_USAGE 


DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 


The service name identified by the hszl parameter should be a base name (that is, 
the name should contain no instance-specific information). The system generates 


_ an instance-specific name and sends it along with the base name during the 
-XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving apphi- 


cations can then connect to the apes application instance. 
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Example The following example initializes an application with the DDEML, creates 
frequently used string handles, and registers the application’s service name: 


HSZ hszClock; 

HSZ hszTime; 

HSZ hszNow; 
HINSTANCE hinst; 
DWORD idInst = @L; 
FARPROC 1pDdeProc; 


/* Initialize the application for the DDEML. */ 

‘IpDdeProc = MakeProcInstance((FARPROC) DdeCallback, hinst); 

if (!DdeInitialize((LPDWORD) &idInst, (PFNCALLBACK) lIpDdeProc, 

APPCMD_FILTERINITS | CBF_FAIL_EXECUTES, @L)) { 

/* Create frequently used string handles. */ 
hszTime = DdeCreateStringHandle(idInst, "Time", CP_WINANSI); 
hszNow = DdeCreateStringHandle(idInst, "Now", CP_WINANSI); 
hszClock = DdeCreateStringHandle(idInst, "Clock", CP_WINANSI); 


/* Register the service name. */ 


DdeNameService(idInst, hszClock, (HSZ) NULL, DNS REGISTER); 


See Also DdeConnect, DdeConnectList, DdeInitialize 


DdePostAdvise Ba 


#include <ddeml.h> 

BOOL DdePostAdvise(idinst, hszTopic, hszItem) 

DWORD idinst; /* instance identifier **/ 
HSZ hszTopic; /* handle of topic-name string | 


HSZ hszltem; /* handle of item-name string sa 


The DdePostAdvise function causes the system to send an XTYP_ADVREQ 
transaction to the calling (server) application’s dynamic data exchange (DDE) call- 
back function for each client that has an advise loop active on the specified topic © 
or item name pair. A server application should call this function whenever the data 
associated with the topic or item name pair changes. 


188 DdePostAdvise 


Parameters 


Return Value 


Errors 


Comments 


Example 


idInst 
Specifies the applicator: instance identifier obtained by a previous call to the 
Ddelnitialize function. 


hszTopic | 
Identifies a string that specifies the topic name. To send notifications for all top- 
ics with active advise loops, an application can set this parameter to NULL. 


hszItem | 
Identifies a string that specifies the item name. To send notifications for all 
items with active advise loops, an application can set this parameter to NULL. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve Bg error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_DLL_USAGE 
DMLERR_NO_ERROR 


_ A server that has nonenumerable topics or items should set the hszTopic and 


hszltem parameters to NULL so that the system will generate transactions for all 
active advise loops. The server’s DDE callback function returns NULL for any ad- | 
vise loops that do not need to be updated. 


If a server calls DdePostAdvise with a topic/item/format name set that includes 
the set currently being handled in a XTYP_ADVREQ callback, a stack overflow 
may result. 


The following example calls the DdePostAdvise function whenever the time 
changes: 


typedef struct { /* tm */ 
int hour; 
int minute; 
int second; 

} TIME; 


TIME tmTime; 


- DWORD idInst; 


HSZ hszTime; 
HSZ hszNow; 


TIME tmCurTime; 


. /* Fill tmCurTime with the current time. #*/ 
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/* Check for any change in second, minute, or hour. 


if ((tmCurTime.second != tmTime.second) | | 
(tmCurTime.minute != tmTime.minute) || 
(tmCurTime.hour != tmTime.hour)) { 
/* Send the current time to the clients. */ 


DdePostAdvise(idInst, hszTime, hszNow); 


See Also Ddelnitialize 


DdeQueryConvinfo 


#include <ddeml.h> 


UINT DdeQueryConvinfo(hCony, idTransaction, lpConvinfo) 
HCONV hConv; /* handle of conversation 
DWORD idTransaction; — _/* transaction identifier 


* / 


e/, 
+ 


CONVINFO FAR® [pConvinfo; /* address of structure with conversation data i 


The DdeQueryConvInfo function retrieves information about a dynamic data ex- 
change (DDE) transaction and about the conversation in which the transaction _ 


takes place. 


Parameters hConv 
Identifies the conversation. 


idTransaction 


Specifies the transaction. For asynchronous transactions, this parameter should 
be a transaction identifier returned by the DdeClientTransaction function. For 
synchronous transactions, this parameter should be QID_SYNC. 


lpConvInfo 


Points to the CONVINFO structure that will receive information about the 
transaction and conversation. The cb member of the CONVINFO structure 
must specify the length of the buffer allocated for the structure. 


The CONVINFO structure has the following form: 
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Return Value 


Errors 


Example 


4Finclude <ddeml.h> 


typedef struct tagCONVINFO { /* ci */ 
DWORD cb; . 
DWORD hUser; 
HCONV hConvPartner; 


HSZ hszSvcPartner; 
HSZ hszServiceReq; 
HSZ hszTopic; 

HSZ hszItem; 

UINT wrmt; 

UINT wlype; 


UINT wStatus; 

UINT wConvst; 

UINT wLastError; 

HCONVLIST hConvList; 

CONVCONTEXT ConvCtxt; 
} CONVINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the number of bytes copied into the CONVINFO structure, if 
the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one 


of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_NO_CONV_ESTABLISHED 
DMLERR_NO_ERROR 
DMLERR_UNFOUND_QUEUE_ID 


The following example fills a CONVINFO structure with information about a syn- 


chronous conversation and then obtains the names of the partner application and 


topic: 7 


DWORD idInst; 

HCONV hConv; 

CONVINFO ci; 

WORD wError; 

char szSvcPartner[32]; 
char szTopic[32]; 

DWORD cchServ, cchTopic; 


if (!DdeQueryConviInfo(hConv, QID_SYNC, &ci)) 
wError = DdeGetLastError(idInst); 


See Also 


DdeQueryNextServer 
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else { 
cchServ = DdeQueryString(idInst, ci.hszSvcPartner, 
(LPSTR) &szSvcPartner, sizeof(szSvcPartner), 
CP_WINANSI); 
cchTopic =DdeQueryString(idInst, ci.hszTopic, 
(LPSTR) &SzTopic, sizeof(szTopic), 
CP_WINANSI); — 


DdeConnect, DdeConnectList, DdeQueryNextServer 


#include <ddeml.h> 

HCONV DdeQueryNextServer(hConvList, hConvPrev) 
HCONVLIST hConvList; /* handle of conversation list */ 
HCONV hConvPrev; _ /* previous conversation handle a 


Parameters 


Return Value 


Example 


The DdeQueryNextServer function obtains the next conversation handle in the 
given conversation list. 


hConvList 


Identifies the conversation list. This handle must have been created by a pre- 
vious call to the DdeConnectList function. 


hConvPrev 
Identifies the conversation handle previously returned by this function. If this 
parameter is NULL, this function returns the first conversation handle in the list. 


The return value is the next conversation handle in the list if the list contains any 
more conversation handles. Otherwise, it is NULL. 


The following example uses the DdeQueryNextServer function to count the num- 
ber of conversation handles in a conversation list and to copy the service-name 
string handles of the servers to a local buffer: 


HCONVLIST hconvList; /* conversation list | 7 ae 
DWORD idInst; | /* instance identifier ef 
HSZ hszSystem; /* System topic ey 
HCONV hconv = NULL; /* conversation handle 2 / 
CONVINFO ci; /* holds conversation data */ 
UINT cConv = Q; /* count of conv. handles */ 


HSZ *pHsz, *aHsz;  $/* point to string handles */ 
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/* Connect to all servers that support the System topic. */ 


hconvList = DdeConnectList(idInst, (HSZ) NULL, hszSystem, 
(HCONV) NULL, (LPVOID) NULL); 


/* Count the number of handles in the conversation list. */ 


while ((hconv = DdeQueryNextServer(hconvList, hconv)) != (HCONV) NULL) 
cConv++; | 


/* Allocate a buffer for the string handles. */ 


hconv = (HCONV) NULL; | 
aHsz = (HSZ *) LocalAlloc(LMEM_FIXED, cConv * sizeof(HSZ)); 


/* Copy the string handles to the buffer. */ 

pHsz = aHsz; 

while ((hconv = DdeQueryNextServer(hconvList, hconv)) != (HCONV) NULL) { 
DdeQueryConvinfo(hconv, QID_SYNC, (PCONVINFO) &ci); 


DdeKeepStringHandle(idInst, ci.hszSvcPartner); 
*pHszt++ = ci.hszSvcPartner; 


. /* Use the handles; converse with servers. */ 


/* Free the memory and terminate conversations. */ 


LocalFree( (HANDLE) aHsz); 
DdeDisconnectList(hconvList); 


See Also ~ DdeConnectList, DdeDisconnectList 


DdeQueryString [ 3.1 | 


_#include <ddeml.h> 
DWORD DdeQueryString(idinst, hsz, lpsz, cchMax, codepage) 
DWORD idInst; /* instance identifier */ 
HSZ hsz; /* handle of string | a f 
LPSTR Ipsz; /* address of destination buffer a 
DWORD cchMax; /* length of buffer **/ 


int codepage; /* code page | */ 
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The DdeQueryString function copies text associated with a string handle into a 
buffer. 


The string returned in the buffer is always null-terminated. If the string is longer 
than (cchMax — 1), only the first (cchMax — 1) characters of the string are copied. 


If the Jpsz parameter is NULL, this function obtains the length, in bytes, of the 
string associated with the string handle. The length does not include the terminat- 
ing null character. | 


Parameters idInst 
_ Specifies the application-instance identifier obtained by a previous call to the 
Ddelnitialize function. 


hsz | 
Identifies the string to copy. This handle must have been created by a previous 
call to the DdeCreateStringHandle function. | 


[psz | 
Points to a buffer that receives the string. To obtain the length of the string, this 
_ parameter should be set to NULL. 


cchMax 
Specifies the length, in bytes, of the buffer pointed to by the /psz parameter. If 
the string is longer than (cchMax — 1), it will be truncated. If the Jpsz parameter 
is set to NULL, this parameter is ignored. | 


codepage 
Specifies the code page used to render the string. This value should be either 
CP_WINANSI or the value returned by the GetKBCodePage function. 


Return Value The return value is the length, in bytes, of the returned text (not including the ter- 
minating null character) if the Jpsz parameter specified a valid pointer. The return 
value is the length of the text associated with the hsz parameter (not including the 
terminating null character) if the Jpsz parameter specified a NULL pointer. The re- 
turn value is NULL if an error occurs. 


Example The following example uses the DdeQueryString function to obtain a service 
| name and topic name that a server has registered: 
UINT type; | 


HSZ hszl; 

HSZ hsz2; 

char szBaseName[16]; 
char szInstName[16]; 


if (type == XTYP_REGISTER) { 
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/* Copy the base service name to a buffer. */ 


DdeQueryString(idInst, hszl, (LPSTR) &szBaseName, 
sizeof(szBaseName), CP_WINANSI); 


/* Copy the instance-specific service name to a buffer. */ 
DdeQueryString(idInst, hsz2, (LPSTR) &szInstName, 


sizeof(szInstName), CP_WINANSI); 
return (HDDEDATA) TRUE; 


} 

See Also DdeCmpStringHandles, DdeCreateStringHandle, pdebrecotne Handle 
Ddelnitialize 

DdeReconnect [3.4] 


#include <ddeml.h> 


HCONV DdeReconnect(hConv) 


HCONV hConvy; 


Parameters 


Return Value 


/* handle of conversation to reestablish */ 


The DdeReconnect function allows a client Dynamic Data Exchange Manage- 
ment Library (DDEML) application to attempt to reestablish a conversation with a 
service that has terminated a conversation with the client. When the conversation 
is reestablished, the DDEML attempts to reestablish any preexisting advise loops. 


hConv 
Identifies the conversation to be reestablished. A client must have obtained the | 


conversation handle by a previous call to the DdeConnect function. 


The return value is the handle of the reestablished conversation if the function is 


successful. The return value is NULL if the function fails. 


Errors 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER | 
DMLERR_NO_CONV_ESTABLISHED 
DMLERR_NO_ERROR | 


Example 


See Also 
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The following example shows the context within which an apeacaon should call 
the DdeReconnect function: 


HDDEDATA EXPENTRY DdeCallback(wType, wFmt, hConv, hszl, 
hsz2, hData, dwDatal, dwData2) | 


WORD wlype; /* transaction type * 
WORD wFmt; /* clipboard format * / 
HCONV hConv; /* handle of the conversation * / 
HSZ hszl; /* handle of a string a / 
HSZ hsz2; /* handle of a string * / 
HDDEDATA hData; /* handle of a global memory object */ 
DWORD dwDatal; /* transaction-specific data * / 
DWORD dwData2; /* transaction-specific data * / 
{ 


BOOL fAutoReconnect; 


switch (wType) { 
case XTYP_DISCONNECT: 
if (fAutoReconnect) { | 
DdeReconnect(hConv); /* attempt to reconnect */ 
} i 7 
return @; 


. /* Process other transactions. */ 


DdeConnect, DdeDisconnect 


DdeSetUserHandle = ao 


#include <ddeml.h> 


-BOOL DdeSetUserHandle(hConv, id, hUser) 


~ HCONV hConv; 
DWORD id; 


DWORD /User; : 


/* handle of conversation a | 
[* transaction identifier *« / 
/* application-defined value | 


The DdeSetUserHandle function associates an application-defined 32-bit value 


- with a conversation handle and transaction identifier. This is useful for simplifying 
_ the processing of asynchronous transactions. An application can use the Dde- 
- QueryConvinfo function to retrieve this value. 3 
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Parameters | 


Return Value 


Errors 


See Also 


DdeUnaccessData 


#include <ddeml.h> 


hConv 
Identifies the conversation. 

id 
Specifies the transaction identifier of an asynchronous transaction. An applica- 
tion should set this parameter to QID_SYNC if no asynchronous transaction is 
to be associated with the hUser parameter. 


hUser 
Identifies the value to associate with the conversation handle. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


DMLERR_DLL_NOT_INITIALIZED 
DMLERR_INVALIDPARAMETER 
DMLERR_NO_ERROR 
DMLERR_UNFOUND_QUEUE_ID 


DdeQueryConvInfo 


BOOL DdeUnaccessData(hData) 


HDDEDATA /hData; 


Parameters 


Return Value 


Errors 


/* handle of global memory object *] 


The DdeUnaccessData function frees a global memory object. An application 
must call this function when it is finished accessing the object. 


hData 
Identifies the Boba memory bicet 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Use the DdeGetLastError function to retrieve the error value, which may be one 
of the following: 


Example 


See Also _ 
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DMLERR_DLL_NOT_INITIALIZED 
DMLERR _INVALIDPARAMETER 
DMLERR_NO_ERROR 


The following example obtains a pointer to a global memory object, uses the 
pointer to copy data from the object to a local buffer, and then uses ; the Dde- 
UnaccessData function to free the object: 


HDDEDATA hData; 

LPBYTE IpszAdviseData; 
DWORD cbDataLen; 

DWORD i; 

char szData[128]; 


IpszAdviseData = DdeAccessData(hData, &cbDataLen); 


for (i = @; i < cbDataLen; i++) 
szDataLi] = *lpszAdviseDatat+; 
DdeUnaccessData(hData) ; 


DdeAccessData, DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle 


DdeUninitialize ec aa 


| #include <ddeml.h> 


- BOOL DdeUninitialize(idinst) 


DWORD idinst; 


Parameters 


Return Value : 


Comments 


/* instance identifier */ 


The DdeUninitialize function frees all Dynamic Data Exchange Management 
Library (DDEML) resources associated with the calling application. 


idInst » | 
Specifies the application- instance identifier obtained by a Prev call to the 
Ddelnitialize function. | 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The DdeUninitialize function terminates any conversations currently open for the 
application. If the partner in a conversation fails to terminate its end of the conver- 
sation, the system may enter a modal loop while it waits for the conversation to ter- 
minate. A timeout period is associated with this loop. If the timeout period expires 
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before the conversation has terminated, a message box appears that gives the user 
the choice of waiting for another timeout period (Retry), waiting indefinitely 
(Ignore), or exiting the modal loop (Abort). 


An application should wait until its windows are no longer visible and its message 
loop has terminated before calling this function. 


See Also DdeDisconnect, DdeDisconnectList, Ddelnitialize 


DebugBreak — 
void DebugBreak(void) 


The DebugBreak function causes a breakpoint exception to occur in the caller. 
This allows the calling process to signal the debugger, forcing it to take some ac- 
tion. If the process is not being debugged, the system invokes the default break- 
point exception handler. This may cause the calling process to terminate. 


Parameters This function has no parameters. 
Return Value This function does not return a value. 
Comments This function is the only way to break into a WEP (Windows exit procedure) in a 


dynamic-link library. 


For more information about using the debugging functions with Microsoft debug- 
ging tools, see Microsoft Windows Programming Tools. 


Example The following example uses the DebugBreak function to signal the debugger im- 
mediately before the application handles the WM_DESTROY message: 


case WM_DESTROY: 
- DebugBreak(); 


PostQuitMessage(Q@); 
break; 7 


See Also WEP 
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DebugOutput | a [ 3.1 | 


void FAR _cdecl DebugOutput(flags, IpszF mt, ...) 
UINT flags; /* type of message i 
LPCSTR I/pszF mt; /* address of formatting string */ 


The DebugOutput function sends a message to the debugging terminal. Applica- 
tions can apply the formatting codes to the message string and use filters and Op- 
tions to control the message category. 


Parameters flags 
Specifies the type of message to be sent to the debugging terminal. This parame- 
ter can be one of the following values: | 


Value Meaning 


DBF_TRACE The message reports that no error has occurred and supplies 
information that may be useful during debugging. Example: 
“t Kernel: LoadResource(14AE of GDI)” 
DBF_WARNING  __ The message reports a situation that may or may not be an 
error, depending on the circumstances. Example: “wn Kernel: 
Global Wire(17BE of GDI) (try GlobalLock)”’ 
DBF_ERROR “ The message reports an error resulting froma failed call to a 
etka Mba. Windows function. The application continues to run. Ex- 
ample: “err Kernel: Peart whee of GDI) (invalid local 
. as, heap)” — 
~ DBF_FATAL The message reports an error that will terminate the applica- 
tion. Example: “fat! User: SetDeskWallpaper(16CA of 
USER)” 


lpszFmt | 
Points to a formatting string identical to the formatting strings used by the Win- 
dows function wsprintf. This string must be less than 160 characters long. Any 
additional formatting can be done by supplying additional parameters following 
lpszFmt. 


Specifies zero or more optional arguments. The number and type of arguments 
depends on the corresponding format- control character reequences specified in 
the /pszF'mt chara : 


Return Value This function does not return a value. 
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Comments The messages sent by the DebugOutput function are affected by the system 
debugging options and trace-filter flags that are set and retrieved by using the 
GetWinDebugInfo and SetWinDebugInfo functions. These options and flags are 
stored ina WINDEBUGINFO structure. 


Unlike most other Windows functions, DebugOutput uses the C calling conven- 
tion (_ cdecl), rather than the Pascal calling convention. As a result, the caller must 
pop arguments off the stack. Also, arguments must be pushed on the stack from 
right to left. In C-language modules, the C compiler performs this task. 


See Also GetWinDebugInfo, OutputDebugString, SetWinDebugInfo, wsprintf 


DebugProc aa] 


LRESULT CALLBACK DebugProc(code, wParam, lParam) 


int code; /* hook code a | 
WPARAM wParam; /* type of hook about to be called =) 
LPARAM /Param; /* address of structure with debugging information sf | 


The DebugProc function is a library-defined callback function that the system 
calls before calling any other filter installed by the Set WindowsHookEx function. 
The system passes information about the filter about to be called to the Debug- 
Proc callback function. The callback function can examine the information ane de- 
termine whether to allow the filter to be called. 


Parameters code 
Specifies the hook code. Currently, HC_ACTION is the only positive valid 
value. If this parameter is less than zero, the callback function must call the 
CallNextHookEx function without any further processing. 


wParam 
Specifies the task handle of the task that installed the filter about to be called. 


[Param 
Contains a long pointer to a DEBUGHOOKINFO structure. The 
DEBUGHOOKINFO structure has the following form: 


Return Value 


Comments 


See Also | 


- DefDigProc 
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typedef struct tagDEBUGHOOKINFO { 
HMODULE hModul eHook; 
LPARAM reserved; 
LPARAM 1Param; 
WPARAM wParam; 
int code; 
} DEBUGHOOKINFO; 


For a full description of this structure, see the M icrosof Windows Program- 
mer’s Reference, Volume 3. 


The callback function should return TRUE to prevent the system from calling 
another filter. Otherwise, the callback function must pass the filter information to 
the CallNextHookEx function. 


An application must install this callback function by specifying the WH_DEBUG 
filter type and the procedure-instance address of the callback function in a call to 
the SetWindowsHookEx function. 


CallWndProc is a placeholder for the library-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the library’ S 
module- definition file. ae 


CallNextHookEx, Set WindowsHookEx 


LRESULT DefDlgProc(hwndDlg, uMsg, wParam, lParam) 


HWND hwnaDig; 
UINT uMsg; 
~WPARAM wParam; 
LPARAM /Param; 


Parameters 


/* handle of dialog box **/ 
/* message **/ 
/* first message parameter */ 
_ /* second message parameter a 


The DefDlgProc function provides default processing for any Windows messages | 
that a dialog box with a private window class does not aaa | : 


hwndDle : 
Identifies the dialog box. 


| uMsg 


Specifies the message to be processed, 


wParam : | 
Prone 16 bits of additional  message- -dependent information. 
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Return Value 


Comments 


See Also 


DefDriverProc 


[Param 
Specifies 32 bits of additional. message-dependent information. 


The return value specifies the result of the message processing and depends on the 
message sent. 


The DefDlgProc function is the window procedure for the DIALOG window 
class. An application that creates new window classes that inherit dialog box 
functionality should use this function. DefDlgProc is not intended to be called as 
the default handler for messages within a dialog box procedure, since doing so 
will result in recursive execution. — 


An application creates a dialog box by calling one of the following functions: 


Function | Description 
CreateDialog Creates a modeless dialog box. 
CreateDialogIndirect | Creates a modeless dialog box. 
CreateDialogIndirectParam Creates a modeless dialog box and passes data to it 
| when it is created. 
CreateDialogParam Creates a modeless dialog box and passes data to it 
| | when it is created. 
DialogBox Creates a modal dialog box. 
DialogBoxIndirect Creates a modal dialog box. 
DialogBoxIndirectParam Creates a modal dialog box and passes data to it 
when it is created. 
DialogBoxParam Creates a modal dialog box and passes data to it 


when it is created. 


DefWindowProc 


LRESULT DefDriverProc(dwDriverldentifier, hdrvr, uMsg, lParamI1, lParam2) 


DWORD dwDriverldentifier; /* installable-driver identifier ial 
HDRVR hdrvr; /* handle of installable driver ss i 
UINT uMsg; /* message number | 
LPARAM /Param1; /* first message parameter */ 
LPARAM /Param2; ‘a second message parameter 7 


The DefDriverProc function provides default Pee for any messages not 
processed by an installable driver. 
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Parameters dwDriverldentifier 
Identifies an installable driver. This parameter must have been obtained by a 
previous call to the OpenDriver function. 
hdrvr 
Identifies the installable driver. 
uMsg | 
Specifies the message to be processed. 


lParam! 
Specifies 32 bits of adaiconal message-dependent information. 


lParam2 
Specifies 32 bits of additional message-dependent information. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The DefDriverProc function processes messages that are not handled by the 
DriverProc function. 


See Also | OpenDriver, SendDriverMessage 


DeferWindowPos Soe Eight [3.0] 


HDWP DeferWindowPos(hdwp, hwnd, hwndInsertAfter, x, y, CX, Ys, hg 


HDWP hdwp; [e handle of internal structure 

HWND hwnd; /* handle of window to position 
HWND hwndInsertAfter; /* placement-order handle **/ 
int x; /* horizontal position “y 
int y; /* vertical position */ 
int cx3 /* width | | | = 
int cy; /* height | ] 
UINT flags; 7 /* window-positioning flags I 


The DeferWindowPos function updates the given internal structure for the given 
window. The function then returns the handle of the updated structure. The End- 
DeferWindowPos function uses the information in this structure to change the 
position and size of a number of windows simultaneously. 


Parameters hdwp 
Identifies an internal structure that contains size and position information for 

one or more windows. This structure is returned by the BeginDeferWindow- 

Pos function or by the most recent call to the DeferWindowPos function. 


204 DeferWindowPos 


- hwnd | | 
Identifies the window for which to store update information in the structure. 


hwndInsertAfter 
Identifies a window that will precede the positioned window in the Z-order. 
This parameter must be a window handle, or one of the following values: 


Value Meaning 


HWND_BOTTOM Places the window at the bottom of the Z-order. If 
, hwnd identifies a topmost window, the window loses 
: its topmost status. 
HWND_TOP Places the window at the top of the Z-order. 
HWND_TOPMOST Places the window above all non-topmost windows. 
The window maintains its topmost position even when 
the window is deactivated. 


HWND_NOTOPMOST Repositions the window to the top of all non-topmost 
windows (that is, behind all topmost windows). 


This parameter is ignored if SWP_NOZORDER is set in the flags parameter. 


X ; 
Specifies the x-coordinate of the window’s upper-left corner. 


Specifies the y-coordinate of the window’s upper-left corner. 


Cx 
Specifies the window’s new width. 


cy 
Specifies the window’s new height. 


flags | 
Specifies one of eight possible 16-bit values that affect the size and position of | 
the window. This parameter can be a combination of the following values: 


Value | Meaning | 
SWP_DRAWFRAME Draws a frame (defined in the window’s class descrip- 7 


tion) around the window. 
SWP_HIDEWINDOW Hides the window. 


SWP_NOACTIVATE Does not activate the window. 
SWP_NOMOVE Retains current position (ignores x and y parameters). 
SWP_NOREDRAW ‘Does not redraw changes. If this flag is set, no repaint- 


ing occurs. This applies to the client area, the non- 
client area (including the title and scroll bars), and any 
part of the parent window uncovered as a result of the 
moved window. When this flag is set, the application 
must explicitly invalidate or redraw any parts of the 

- window and parent window that must be redrawn. 


~~ Return Value 


Comments 
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Value | Meaning 

SWP_NOSIZE Retains current size (ignores the cx and cy parameters). 

SWP_NOZORDER Retains current ordering (ignores the hwndInsertAfter 
parameter). 


SWP_SHOWWINDOW Displays the window. 


The return value is a handle of the updated structure if the function is successful. 
This handle may differ from the one passed to the function as the hdwp parameter 


and should be passed to the next call to Defer WindowPos or to the EndDefer- 


WindowPos function. 


The return value is NULL if insufficient system resources are available for the 
function to complete successfully and the repositioning process is terminated. 


If a call to Defer WindowPos fails, the application should abandon the window- 
positioning operation without calling the EndDeferWindowPos function. 


If SWP_NOZORDER is not specified, Windows places the window identified 

by hwnd in the position following the window identified by hwndInsertAfter. If 
hwndInsertAfter is NULL, Windows places the window identified by hwnd at the 
top of the list. If hwndInsertAfter is HWND_BOTTOM, Windows places the win- 


dow identified by hwnd at the bottom of the list. 


All coordinates for child windows are relative to the upper-left corner of the parent 
window’s client area. 


A window can be made a topmost window either by setting hwndInsertAfter to 
HWND_TOPMOST and ensuring that SWP_NOZORDER is not set, or by setting 
a window’s Z-order so that it is above any existing topmost windows. When a non- 
topmost window is made topmost, its owned windows are also made topmost. Its _ 
owners are not changed. 


_ If neither SWP_NOACTIVATE nor SWP_NOZORDER is specified (that is, 


when the application requests that a window be simultaneously activated and 
placed in the specified Z-order), the value specified in hwndInsertAfter is used 
only in the following circumstances: | 


= Neither HWND_TOPMOST nor HWND_NOTOPMOST is specified in the 
hwndInsertAfter parameter. 


= The window specified in the hwnd parameter is not the active window. 


An application cannot activate an inactive window without also bringing it to the 
top of the Z-order. Applications can change the Z-order of an activated window 
without restrictions or activate a window and then move it to the top of the top- 
most or non-topmost windows. 
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A topmost window is no longer topmost if it is repositioned to the bottom * 
(HWND_BOTTOM) of the Z-order or after any non-topmost window. When a 
topmost window is made non-topmost, the window and all of its owners, and its 
owned windows, are also made non-topmost. 


A non-topmost window may own a topmost window, but not vice versa. Any win- 
dow (for example, a dialog box) owned by a topmost window is itself made top- 
most to ensure that all owned windows stay above their owner. 


SeeAlso BeginDeferWindowPos, EndDeferWindowPos 


DefFrameProc 


LRESULT DefF rameProc(hwnd, hwndMDIClient, uMsg, wParam, lParam) 
*/ 


HWND hwnd; /* handle of frame window 

HWND hwndMDiIClient; /* handle of client window */ 
UINT uMsg; /* message **/ 
WPARAM wParam; /* first message parameter | */ 
LPARAM /Param; /* second message parameter */ 


The DefFrameProc function provides default processing for any Windows mes- 
sages that the window procedure of a multiple document interface (MDI) frame 
window does not process. All window messages that are not explicitly processed 

y by the window procedure must be passed to the DefFrameProc function, not the 
DefWindowProc function. 


Parameters hwnd 
Identifies the MDI frame window. 


hwndMDIClient 
Identifies the MDI client window. 


uMsg 
Specifies the message to be processed. 


wParam 
Specifies 16 bits of additional message- “dependent information. 


[Param 
| Specifies 32 bits of additional message- -dependent information. 


Return Value The return value specifies the result of the message processing atid depends on the 
message sent. If the hwndMDIClient parameter is NULL, the return value is the 
same as for the DefWindowProc function. 
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Comments Typically, when an application’s window procedure does not handle a message, it 
passes the message to the DefWindowProc function, which processes the mes- 
sage. MDI applications use the DefFrameProc and DefMDIChildProc functions 
instead of DefWindowProc to provide default message processing. All messages 
that an application would usually pass to DefWindowProc (such as nonclient mes- 
sages and WM_SETTEXT) should be passed to DefFrameProc instead. In addi- 
tion to handling these messages, DefFrameProc also handles the following 


messages: 


Message 
WM_COMMAND 


WM_MENUCHAR 


WM_SETFOCUS 


WM_SIZE 


Response 


The frame window of an MDI application receives the 


WM_COMMAND message to activate a particular MDI child 
window. The window identifier accompanying this message 
will identify the MDI child window assigned by Windows, 
starting with the first identifier specified by the application 
when it created the MDI client window. This value of the first 
identifier must not conflict with menu-item identifiers. 


When the user presses the ALT+— key combination, the System 
menu (often called Control menu) of the active MDI child win- 
dow will be selected. 


DefFrameProc passes focus on to the MDI client, which in 
turn passes the focus on to the active MDI child window. 


If the frame window procedure passes this message to Def- 


-FrameProc, the MDI client window will be resized to fit in 


the new client area. If the frame window procedure sizes the 
MDI client to a different size, it should not pass the message to 
DefWindowProc. 


See Also ~ DefMDIChildProc, DefWindowProc 


DefHookProc 


DWORD DefHookProc(nCode, uParam, aibavain. eo 


int nCode; /* process code */ 
UINT uParam; /* first message parameter | ic ey 
DWORD dwParam; /* second message parameter _ a 
HHOOK FAR?® [phhook; /* points to address of next hook function */ 


This function is obsolete but has been retained for backward compatibility with 
Windows versions 3.0 and earlier. Applications written for Windows version 3.1 
~ should use the CallNextHookEx function. 
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Parameters 


Return Value 


Comments 


See Also 


DefMDIChild 


The DefHookProc function calls the next function in a chain of hook functions. A 
hook function is a function that processes events before they are sent to an applica- 
tion’s message-processing loop in the WinMain function. When an application de- 
fines more than one hook function by using the SetWindowsHook function, 
Windows forms a linked list or hook chain. Windows places functions of the same 
type in a chain. 


nCode 
Specifies a code used by the Windows hook function (also called the message- 
filter function) to determine how to process the message. 


uParam 
Specifies 16 bits of additional message-dependent information. 


dwParam 
Specifies 32 bits of additional message-dependent information. 


lphhook | 
Points to the variable that contains the procedure-instance address of the pre- 
viously installed hook function returned by the SetWindowsHook function. 


The return value specifies the result of the event processing and depends on the 
event. 


Windows changes the value at the location pointed to by the Iphhook parameter 
after an application calls the Unhook WindowsHook function. For more informa- 
tion, see the description of the UnhookWindowsHook function. 


Set WindowsHook, Unhook WindowsHook 


Proc oe 


LRESULT DefMDIChildProc(hwnd, uMsg, wParam, lParam) 


HWND hwnd; 
UINT uMsg; 
WPARAM wParam; 
LPARAM /Param; 


/* handle of child window sg | 
/* message */ 
/* first message parameter */ 
/* second message parameter */ 


The DefMDIChildProc function provides default processing for any Windows 
messages that the window procedure of a multiple document interface (MDI) child 


_ window does not process. All window messages that are not explicitly processed 


by the window procedure must be passed to the Def{MDIChildProc function, not 
the DefWindowProc function. 


Parameters 


Return Value 


Comments 


See Also — 
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hwnd 
Identifies the MDI child window. 


uMsg 
Specifies the message to be processed. 


wParam 
Specifies 16 bits of additional message-dependent information. 


lParam 
Specifies 32 bits of additional message-dependent information. 


The return value specifies the result of the message processing and depends on the 
message sent. | m3 


This function assumes that the parent of the window identified by the hwnd pa- 
rameter was created with the MDICLIENT class. | 


Typically, when an application’s window procedure does not handle a message, it 
passes the message to the DefWindowProc function, which processes the mes- 
sage. MDI applications use the DefFrameProc and DefMDIChildProc functions 
instead of DefWindowProc to provide default message processing. All messages 
that an application would usually pass to DefWindowProc (such as nonclient mes- 
sages and WM_SETTEXT) should be passed to Def{MDIChildProc instead. In ad- 
dition to handling these messages, DefMDIChildProc also handles the following _ 
messages: | | | | 


Message Response 
WM_CHILDACTIVATE Performs activation processing when child windows are 
sized, moved, or shown. This message must be passed. 


WM_GETMINMAXINFO Calculates the size of a maximized MDI child window 
based on the current size of the MDI client window. 


WM_MENUCHAR Sends the keystrokes to the frame window. 
WM_MOVE Recalculates MDI client scroll bars, if they are present. 
WM_SETFOCUS Activates the child window if it is not the active MDI 
child window. 
WM_SIZE | Performs necessary operations when changing the size 


of a window, especially when maximizing or restoring 
an MDI child window. Failing to pass this message to 
DefMDIChildProc will produce highly undesirable re- 
sults. 


~ WM_SYSCOMMAND Also handles the next window command. 


- DefFrameProc, DefWindowProc 
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DefWindowProc 


LRESULT DefWindowProc(hwnd, uMsg, wParam, lParam) 


HWND hwnd; 
UINT uMsg; 
WPARAM wParam; 
LPARAM /Param; 


Parameters 


Return Value 
Comments 


Example 


4 


/* handle of window 7 
/* type of message sad 
/* first message parameter a | 
/* second message parameter .  */ 


The DefWindowProc function calls the default window procedure. The default 
window procedure provides default processing for any window messages that an 
application does not process. This function ensures that every message is 
processed. It should be called with the same parameters as those received by the 
window procedure. 


hwnd 3 
Identifies the window that received the message. 


uMsg 
Specifies the message. 


wParam ; 
Specifies 16 bits of additional message-dependent information. 


lParam 
Specifies 32 bits of additional message-dependent information. 


The return value is the result of the message processing and depends on the mes- 
Sage sent. | 


The source code for the DefWindowProc function is provided on the Microsoft 
Windows 3.1 Software Development Kit (SDK) disks. 


The following example shows a typical window procedure. A switch statement is 
used to process individual messages. All messages not processed are passed on to 
the DefWindowProc function. 


LONG FAR PASCAL MainWndProc(hwnd, message, wParam, |]Param) 


HWND hwnd; ~ /* handle of window ok / 
WORD message; /* type of message * / 
WORD wParam; /* additional information */ 
LONG 1Param; /* additional information */ 


switch (message) 1 


See Also 


DeleteAtom 
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fe 
* Process whatever messages you want here and send the 
* rest to DefWindowProc. 
* / 


default: 
return (DefWindowProc(hwnd, message, wParam, |]Param)); 


DefDigProc 


Bx 


ATOM DeleteAtom(atm) 
ATOM atm; /* atom to delete */ 


Parameters 
Return Value | 


Comments | 


Example 


The DeleteAtom function decrements (decreases by one) the reference count of a 
local atom by one. If the atom’s reference count is reduced to zero, the string as- 


sociated with the atom is removed from the local atom table. 


An atom’s reference count specifies the number of times the atom has been added > 
to the atom table. The AddAtom function increments (increases by one) the count 
on each call. DeleteAtom decrements the count on each call and removes the 
string only if the atom’ s reference count is reduced to zero. 


aim 
Identifies the atom and character string to be deleted. 


The return value is zero if the function is successful: Otherwise, it is s equal to the 
atm parameter. 3 


The only way to ensure that an atom has been deleted from the atom table is to call 
this function repeatedly until it fails. When the count is decremented to zero, the 
next call to the FindAtom or DeleteAtom function will fail. 


DeleteAtom has no effect on integer atoms (atoms created by using the MAKE- 


IINTATOM macro). The function always returns zero for integer atoms. 


The following example uses the DeleteAtom function to decrement the reference 
count for the specified atom: 


ATOM at; 


at = DeleteAtom(atTest); 


212 DeleteDC 


See Also 


DeleteDC 


if (at == NULL) 
MessageBox(hwnd, "atom count decremented", 
"DeleteAtom", MB_OK); 
else 
MessageBox(hwnd, “atom count could not be decremented", 
"DeleteAtom", MB_ICONEXCLAMATION) ; 


AddAtom, FindAtom, GlobalDeleteAtom 


BOOL DeleteDC (hdc) 
HDC hdc; /* handle of device context */ 


Parameters 


Return Value 


Comments 


Example 


The DeleteDC function deletes the given device context. 


hdc 
Identifies the device context. 


The return value is nonzero if the function is successful. Otherwise, it 1s zero. 


If the hdc parameter identifies the last device context for a given device, the 


device is notified and all storage and system resources used by the device are 
released. 


An application must not delete a device context whose handle was retrieved by 
calling the GetDC function. Instead, the application must call the ReleaseDC 
function to free the device context. 


An application should not call DeleteDC if the application has selected objects 
into the device context. Objects must be selected out of the device context before 
it is deleted. 


The following example uses the CreateDC function to create a device context for 


a printer and then calls the DeleteDC function when the device context is no 


longer needed: 
/* Retrieves a device context for a printer. */ 


hdcPrinter = CreateDC(1pDriverName, IpDeviceName, IpOutput, 
IpInitData) ; 


. /* Use the device context. */ 
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/* Delete the device context. */ 


DeleteDC(hdcPrinter); 


See Also _ CreateDC, GetDC, ReleaseDC 


DeleteMenu 


BOOL DeleteMenu(imenu, idltem, fuF lags) 

HMENU hmenu; /* handle of menu 

UINT idltem; /* menu-item identifier */ 

UINT fuFlags; /* menu flags wi 
The DeleteMenu function deletes an item from a menu. If the menu item has an 
associated pop-up menu, DeleteMenu destroys the handle of the pop- up menu and 
frees the ey used by the pop-up menu. 


Parameters hmenu 
Identifies the menu to be changed. 


idltem 
Specifies the menu item to be deleted, as determined by the fuFlags Parameter; 


fuF lags 
Specifies how the idltem parameter is interpreted. This parameter can be one of © 


the following values: 
Value Meaning 


MF_BYCOMMAND The idltem parameter specifies the menu-item identifier. 


MF_BYPOSITION _ The idItem parameter specifies the zero-based relative 
position of the menu item. 


Return Value The return value is nonzero if the function is successful. Otherwise, it iS zero. 


Comments — - Whenever a menu changes (whether or not the menu is in a window that is dis- _ 
played), the application should call the DrawMenuBar function. _ 


See Also — _ AppendMenu, CreateMenu, DrawMenuBar, InsertMenu, RemoveMenu 
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DeleteMetaFile Pax | 


BOOL DeleteMetaFile(im/) 
HMETAFILE him; /* handle of metafile */ 


The DeleteMetaFile function invalidates the given metafile handle. 


Parameters hmf 
, Identifies the metafile to be deleted. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The DeleteMetaFile function does not destroy a metafile that is saved on disk. 
After calling DeleteMetaFile, an application can retrieve a new handle of the 
metafile by calling the GetMetaFile function. 


Example The following example uses the CreateMetaFile function to create the handle of a 
| memory metafile device context, draws a line in that device context, retrieves a 
handle of the metafile by calling the CloseMetaFile function, plays the metafile 
by using the PlayMetaFile function, and finally deletes the metafile by using 
DeleteMetaFile: 


HDC hdcMeta; 
HMETAFILE hmf; 


hdcMeta = CreateMetaFile(NULL); 
MoveTo(hdcMeta, 10, 10); 
LineTo(hdcMeta, 100, 100); | 
hmf = CloseMetaFile(hdcMeta) ; 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf); 


See Also CreateMetaFile, GetMetaFile 


DeleteObject | a [2x] 


BOOL DeleteObject(jgdiobj) 7 | 
HGDIOBJ hediobj; /* handle of object to delete oy 


The DeleteObject function deletes an object from memory by freeing all system 
storage associated with the object. (Objects include pens, brushes, fonts, bitmaps, 
regions, and palettes.) | 


Parameters 


Return Value 


Comments 


Example 


See Also 


DestroyCaret 
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hgdiobj 
Identifies a pen, brush, font, bitmap, region, or palette. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


After the object is deleted, the handle given in the hgdiobj parameter is no longer 
valid. — 


An application should not delete an object that is currently selected into a device 
context. 


When a pattern brush is deleted, the bitmap associated with the beast is not de- 
leted. The bitmap must be deleted independently. 


The following example creates a pen, selects it into a device context, and uses the 
pen to draw a rectangle. To delete the pen, the original pen is selected back into 
the device context and the DeleteObject function is called. 


HPEN hpen, hpenOld; 


hpen = CreatePen(PS SOLID, 6, RGB(Q, @, 255)); 


hpenOld = SelectObject(hdc, hpen); 


Rectangle(hdc, 10, 10, 100, 100); 


SelectObject(hdc, hpen0ld); 


} DeleteObject(hpen) ; 


SelectObject 


= 


void DestroyCaret( void) 


Parameters 


Return Value 


The DestroyCaret function destroys the current caret shape, frees the caret from — 
the window that currently owns it, and removes the caret from the screen ifitis 
visible. The DestroyCaret function checks the ownership of the caret and de- 


_ Stroys the caret only if a window in the current task owns it. 
If the caret shape was previously a bitmap, DestroyCaret does not free the ee 


This function has no parameters. 


This function does not return a value. 
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Comments The caret is a shared resource. If a window has created a caret shape, it should de- 


stroy that shape before it loses the input focus or becomes inactive. 


See Also CreateCaret, HideCaret, ShowCaret 


DestroyCursor — | 


BOOL DestroyCursor(hcur) 
HCURSOR heur; /* handle of cursor to destroy 9 


The DestroyCursor function destroys a cursor that was previously created by the 
CreateCursor or LoadCursor function and frees any memory that the cursor oc- 
cupied. 


Parameters heur 
Identifies the cursor to be destroyed. The cursor must not be in current use. 


Return Value - The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also CreateCursor, Createlcon, DestroyIcon, LoadCursor 


Destroyicon 


BOOL Destroylcon(hicon) 
HICON hicon; /* handle of icon to destroy +} 


. The DestroyIcon function destroys an icon that was created by the CreateIcon or 
LoadIcon function and frees any memory that the icon occupied. 


Parameters hicon 
| Identifies the icon to be destroyed. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also CreateCursor, CreateIcon, DestroyCursor, LoadIcon 
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DestroyMenu its ex] 


BOOL DestroyMenu(hmenu) - | 
HMENU hmenu; /* handle of menu to destroy */. 


The DestroyMenu function destroys a menu and frees any memory that the menu 
occupied. | 


Parameters hmenu 
Identifies the menu to be destroyed. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also | CreateMenu 


DestroyWindow tit ee £5 


BOOL Destroy Window(hwnd) 
— HWND hwnd; /* handle of window to destroy ad | 


The Destroy Window function destroys the specified window. The function sends 
appropriate messages to the window to deactivate it and remove the input focus. It 
also destroys the window’s menu, flushes the application queue, destroys outstand- 
ing timers, removes clipboard ownership, and breaks the clipboard-viewer chain 
(if the window is at the top of the viewer chain). It sends WM_ DESTROY and 
WM_NCDESTROY meseoses to the window. | 


If the given window is the parent of any windows, Destroy Window automatically — 
destroys these child windows when it destroys the parent window. The function de- 
stroys child windows first, and then the window itself. 


_ The Destroy Window function also destroys modeless dialog boxes created by the 
_ CreateDialog function. 


Parameters — hwnd | 
| Identifies the window to be destroyed. — 


Return Value — - The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments If the window being destroyed is a child window and does not have the 
| WS_NOPARENTNOTIPY style set, a WM_PARENTNOTIFY message is sent to 
the ea 
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Example The following example responds to the application-defined menu command 
IDM_EXIT, and then calls Destroy Window to destroy the window: 


case IDM EXIT: 
DestroyWindow(hwnd); 
return Q; 


See Also CreateDialog, CreateWindow, CreateWindowEx 


DeviceCapabilities 
#include <print.h> 


DWORD DeviceCapabilities(/pszDevice, IpszPort, fwCapability, lpszOutput, Ipdm) 
*/ 


LPSTR IpszDevice; /* address of device-name string 
LPSTR IpszPort; /* address of port-name string sy 
WORD fwCapability; /* device capability to query ‘| 
LPSTR [pszOutput; /* address of the output sf 
LPDEVMODE Ipdm; _‘/* address of structure with device data ey: 
The DeviceCapabilities function retrieves the capabilities of the printer device 
driver. 
Parameters IpszDevice 
Points to a null-terminated string that contains the name of the printer device, 
such as PCL/HP LaserJet. 
lpszPort 


Points to a null-terminated string that contains the name of the port to which the 
device is connected, such as LPT1. 


fwCapability 
Specifies the capabilities to query. This parameter can be one of the following 
values: 

Value Meaning 

DC_BINNAMES Copies an array containing a list of the names of 


the paper bins. This array is in the form char 
PaperNames|cBinMax]|{cchBinName] where 
cchBinName is 24. If the IpszOutput parameter is 
NULL, the return value is the number of bin en- 
tries required. Otherwise, the return value is the 
number of bins copied. 


Value 
DC_BINS 


DC_COPIES 
DC_DRIVER 
DC_DUPLEX 


DC_ENUMRESOLUTIONS 


DC_EXTRA 


DC_FIELDS 


DC_FILEDEPENDENCIES 


DC_MAXEXTENT 


DC_MINEXTENT 
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Meaning 


Retrieves a list of available bins. The function co- 
pies the list to the JpszOutput parameter as a 
WORD array. If pszOutput is NULL, the function 
returns the number of supported bins to allow the 


_ application the opportunity to allocate a buffer 


with the correct size. For more information about 
these bins, see the description of the dmDefault- 
Source member of the DEVMODE structure. 


Returns the number of copies the device can print. 
Returns the version number of the printer driver. 
Returns the level of duplex support. The function 


returns 1 if the printer is capable of duplex print- 
ing. Otherwise, the return value is zero. 


Returns a list of available resolutions. If 
[pszOutput is NULL, the function returns the num- 
ber of available resolution configurations. Resolu- 
tions are represented by pairs of LONG integers 


representing the horizontal and vertical resolutions 


(specified in dots per inch). 


Returns the number of bytes required for the 
device-specific portion of the DEVMODE struc- 
ture for the printer driver. 


Returns the dmFields member of the printer 
driver’s DEVMODE structure. The dmFields 
member indicates which fields in the device- 
independent portion of the structure are supported 
by the printer driver. 


Returns a list of files that also need to be loaded 
when a driver is installed. If the JpszOutput pa- 
rameter is NULL, the function returns the number 
of files. Otherwise, [pszOutput points to an array 
of filenames in the form char[chFileName, 64]. 
Each filename is a null-terminated string. 


Returns a POINT structure containing the maxi- 
mum paper size that the dmPaperLength and 
dmPaperWidth members of the printer driver’s 
DEVMODE structure can specify. 3 


Returns a POINT structure containing the min- 
imum paper size that the dmPaperLength and 
dmPaperWidth members of the printer driver’s 
DEVMODE structure can specify. 
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Value 


DC_ORIENTATION 


DC_PAPERNAMES 


DC_PAPERS 


~DC_PAPERSIZE 


_ DC_SIZE 


Meaning 


Returns the relationship between portrait and land- 


‘scape orientations for a device, in terms of the 


number of degrees that portrait orientation is ro- 
tated counterclockwise to produce landscape orien- 
tation. The return value can be one of the 
following: 


Value Meaning 
0 No landscape orientation. 
90 Portrait is rotated 90 degrees to pro- 


duce landscape. (For example, 
Hewlett-Packard PCL printers.) 


ZIQ: : Portrait is rotated 270 degrees to pro- 
duce landscape. (For example, dot- 
matrix printers.) 


Retrieves a list of supported paper names—for ex- 
ample, Letter or Legal. If the IpszOutput parameter 
is NULL, the function returns the number of paper 
sizes available. Otherwise, /pszOutput points to an 
array for the paper names in the form char[cPaper- 


_ Names, 64]. Each paper name is a null-terminated 


string. 
Retrieves a list of supported paper sizes. The func- 


tion copies the list to IpszOutput asa WORD 


array and returns the number of entries in the 
array. If IpszOutput is NULL, the function returns 
the number of supported paper sizes to allow the 
application the opportunity to allocate a buffer 
with the correct size. For more information on 
paper sizes, see the description of the dmPaper- 
Size member of the DEVMODE structure. | 


Copies the dimensions of all supported paper 
sizes, in tenths of a millimeter, to an array of 
POINT structures pointed to by the /pszOutput 
parameter. The width (x-dimension) and length 
(y-dimension) of a paper size are returned as if the 
paper were in the DMORIENT_PORTRAIT orien- — 
tation. © | 


_ Returns the dmSize member of the printer driver’s 


DEVMODE structure. 


DC_TRUETYPE 


DC_VERSION 


IpszOutput 


DeviceCapabilities 


Retrieves the abilities of the driver to use True- 
Type fonts. The return value can be one or more of 


the following: 
Value 


DCTT_BITMAP 


DCTT_DOWNLOAD 


DCTT_SUBDEV 


Meaning 


Device is capable of 
printing TrueType 
fonts as graphics. (For 
example, dot-matrix 
and PCL printers.) 


Device is capable of 
downloading TrueType 
fonts. (For example, 
PCL and PostScript 
printers.) 


Device is capable of 
substituting device 
fonts for TrueType 
fonts. (For example, 
PostScript printers.) 


For DC_TRUETYPE, the [pszOutput parameter 


should be NULL. 


Returns the specification version to which the 


printer driver conforms. 
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- Points to an array of bytes. The format of the array depends on the setting of the 
fwCapability parameter. If IpszOutput is zero, DeviceCapabilities returns the 
number of bytes required for the output data. 


lpdm 


Points to a DEVMODE structure. If this parameter is NULL, Device- 
Capabilities retrieves the current default initialization values for the specified 


printer driver. Otherwise, the function retrieves the values contained in the 


structure to which pdm points. 
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The DEVMODE structure has the following form: 


#Finclude <print.h> 


typedef struct tagDEVMODE { /* dm */ 
char dmDeviceNameLCCHDEVICENAME ] ; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDriverExtra; 
DWORD dmFields; 
int dmOrientation; 
int dmPaperSize; 
int dmPaperLength; 
int dmPaperWidth; 
int dmScale; 
int dmCopies; 
int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; 
int dmDuplex; 
int dmYResolution; 
int dmTTOption; 
} DEVMODE; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


~ Return Value The return value, if the function is successful, depends on the setting of the 
fwCapability parameter. The return value is —1 if the function fails. 


Comments This function is supplied by the printer driver. To use the DeviceCapabilities func- 
tion, an application must retrieve the address of the function by calling the Load- 
Library and GetProcAddress functions, and it must include the PRINT.H file. 


DeviceCapabilities is not supported by all printer drivers. If the GetProcAddress 
function returns NULL, DeviceCapabilities is not supported. 


See Also GetProcAddress, LoadLibrary 


DeviceMode 
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[ 2.x | 


void DeviceMode(hwnd, hModule, lpszDevice, IpszOutput) 


HWND hwnd; 

HANDLE hModule; 
LPSTR IpszDevice; 
LPSTR [pszOutput; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of window owning dialog box pa 
/* handle of printer-driver module tf 
/* address of string for device name */ 
/* address of string for output name 2 


The DeviceMode function sets the current printing modes for a specified device 
by using a dialog box to prompt for those modes. An application calls Device- 
Mode to allow the user to change the printing modes of the corresponding device. 
DeviceMode copies the mode information to the environment block that is as- 
sociated with the device and maintained by the graphics device interface (GDI). 


The ExtDeviceMode function provides a superset of the functionality of the 
DeviceMode function; new applications should use ExtDeviceMode instead of 
DeviceMode whenever possible. (Applications can use the DM_IN_ PROMPT 
constant with ExtDeviceMode to duplicate the functionality of DeviceMode.) 


hwnd 
Identifies the window that will own the dialog box. 
hModule 


Identifies the printer-driver module. The application should retrieve this handle 
by calling either the GetModuleHandle or LoadLibrary function. 


[pszDevice 


Points to a null- terminated string that seeeraes iie'n name of the specific device 
to be supported (for example, Epson FX-80). The device name is the same as 
the name passed to the CreateDC function. , 


IpszOutput 
Points to a null-terminated string that specifies the MS-DOS filename or device 
name for the physical output medium (file or output port). The output name is 
the same as the name passed to the CreateDC function. 


This function does not return a value. 


The DeviceMode function is part of the printer’s device driver, not part of GDI. 
To call this function, an application must load the printer driver by calling the 
LoadLibrary function and retrieve the address of the function by using the Get- 


-ProcAddress function. The application can then use the address to set up the 


printer. 


DeviceMode is not supported by all printer drivers. If the GetProcAddress fune- 
tion returns NULL, DeviceMode is not supported. © 


CreateDC, ExtDeviceMode, GetModuleHandle, LoadLibrary 
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DialogBox 


int DialogBox(hinst, lpszDlgTemp, hwndOwner, dlgprc) 


HINSTANCE hinst; /* handle of application instance */ 
LPCSTR [pszDlgTemp; /* address of dialog box template name sa 
HWND hwndOwner; /* handle of owner window | */ 
DLGPROC digprc; /* instance address of dialog box procedure +) 


Parameters 


The DialogBox function creates a modal dialog box from a dialog box template re- 
source. 


hinst 


Identifies an instance of the module whose executable file contains the dialog 
box template. | 


| lpszDlgTemp 


Return Value 


Comments 


Example 


Points to a null-terminated string that names the dialog i ee 


hwndOwner 
Identifies the window that owns the dialog box. 


dlgprc 
Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog- 
Proc callback function. | 


The return value specifies the value of the nResult parameter specified in the End- 
Dialog function that is used to terminate the dialog box. The system processes 
values returned by the dialog box procedure and does not return them to the appli- 
cation. The return value is —1 if the function cannot create the dialog box. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if DS_SETFONT style was 
specified) and a WM_INITDIALOG message, and then the dialog box is dis- 
played. 


The DialogBox function does not return control until 1 the dialog box procedure ter- 
minates the modal dialog box by calling the EndDialog function. 


A dialog box can contain up to 255 controls. 


The following example uses the DialogBox function to create a modal dialog box: 


DLGPROC digprc; 
HWND hwndParent; 


See Also” 


DialogBoxindirect 
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case IDM ABOUT: 
digprc = (DLGPROC) MakeProcInstance(About, hinst); 
DialogBox(hinst, "“AboutBox", hwndParent, dlgprc); 
FreeProcInstance((FARPROC) dlgprc); 
break; 


DialogBoxIndirect, DialogBoxIndirectParam, piace oR aram: DialogProc, 
EndDialog, GetDC, MakeProcInstance 


int DialogBoxIndirect(hinst, hglbDlgTemp, hwndOwner, digprc) 


HINSTANCE hinst; /* handle of application instance | | > oe 
HGLOBAL heglbDlgTemp; /* handle of memory with dialog box eniaie: i 
HWND hwndOwner; /* handle of owner window a | 
~ DLGPROC dlgprc; /* instance address of dialog box procedure | 


Parameters 


Return Value — 


The DialogBoxIndirect function creates a modal dialog box from a dialog box 
template in memory. 


hinst 
Identifies the instance of the module that will create the dialog box. 


hglbDigTemp 
Identifies the global memory object that contains a dialog box template used to 
create the dialog box. This template is in the form of a DialogBoxHeader struc- 
ture. For more information about this structure, see Chapter 7, “Resource For- 
mats Within Executable Files,” in the Microsoft Windows Programmer’s 
Reference, Volume 4. 


hwndOwner 
Identifies the window that owns the dialog box. 


dlgprc ae 

Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog: 
Proc callback function. | 


The. return value is the value of the nResult parameter specified in the EndDialog — 
function that is used to terminate the dialog box. The system processes values re- 
turned by the dialog box procedure and does not return them to the application. — 
The return value is —1 if the function cannot create the dialog box. 
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Comments 


Example 


The Create WindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message Gif DS_SETFONT style was 
specified) and a WM_INITDIALOG message, and then the dialog box is dis- 
played. 


The DialogBoxIndirect function does not return control until the dialog box pro- 
cedure terminates the modal dialog box by calling the EndDialog function. 


A dialog box can contain up to 255 controls. | 


The following example uses the DialogBoxIndirect function to create a dialog 
box from a dialog box template in memory: 


dtedefine TEMPLATE_SIZE 100 
HGLOBAL hglbD1lgTemp; 
DLGPROC dlgprc; 

int result; 


- HWND hwndParent; 


See Also 


DialogBoxindirectParam 


/* Allocate a global memory object for the dialog box template. 2 / 


hglbDlgTemp = GlobalAlloc(GHND, TEMPLATE_SIZE); 
. /* Build a DLGTEMPLATE structure in the memory object. */ 


digprc 
result 


(DLGPROC) MakeProcInstance(DialogProc, hinst); 
DialogBoxIndirect(hinst, hglbDIgTemp, hwndParent, dlgprc); 


DialogBox, DialogBoxIndirectParam, DialogBoxParam, DialogProc, End- 
Dialog, MakeProclInstance 


int DialogBoxIndirectParam(hinst, hglbDigTemp, hwndOwner, dlgprc, [ParamInit) 


HINSTANCE hinst; /* handle of application instance i 
HGLOBAL hglbDigTemp; /* handle of memory with dialog box template */ 
HWND hwndOwner; /* handle of owner window | =] 
DLGPROC dlgprc; /* instance address of dialog box procedure */ 
LPARAM ani /* initialization value . 7 =] 


The DialogBoxIndirectParam function creates ; a modal dialog box from a dialog 
box template in memory. Before displaying the dialog box, the function passes an 
application-defined value to the dialog box procedure as the /Param parameter of 


Parameters 


Return Value 


Comments 


Example : 
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the WM_INITDIALOG message. An application can use this value to initialize 
dialog box controls. 


hinst 
Identifies the instance of the module that will create the dialog box. 


hglbDligTemp 
Identifies the global memory object that contains a dialog box template used to 
create the dialog box. This template is in the form of a DialogBoxHeader struc- 
ture. For more information about this structure, see Chapter 7, “Resource For- 
mats Within Executable Files,” in the Microsoft Windows Programmer’s 
Reference, Volume 4. _ 


hwndOwner 
Identifies the window that owns the dialog box. 


dlgprc 
Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProcInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog: 
Proc callback function. 


[Paramlnit 
Specifies a 32-bit value that DialogBoxIndirectParam passes to the aloe box 
when the WM_INITDIALOG message is being processed. 


The return value is the value of the nResult parameter specified in the EndDialog | 
function that is used to terminate the dialog box. The system processes values re- 
turned by the dialog box procedure and does not return them to the applications: 
The return value 1 is —1 if the function cannot create the ee box. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if DS_SETFONT style was | 
specified) and a WM_INITDIALOG message, and then the dialog box i 1S S dis- 
played. | 


The DialogBoxIndirectParam function does not return control until the dialog 
_ box procedure terminates the modal dialog box by calling the EndDialog function. 


A dialog box can contain up to 255 controls. 


‘The following example uses the DialogBoxIndirectParam function tocreatea : 
modal dialog box from a dialog box template in memory. The example uses the 
1ParamInit parameter to send two initialization parameters (wInitParm1 and 


wInitParm2) to the dialog | box procedure when the WM _IN OS message i 1S” 


_ being processed. 
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m 


dKdefine TEMPLATE_SIZE 100 
HGLOBAL hglbDIgTemp; 


. DLGPROC dlgprc; 


See Also 


DialogBoxPa 


int result; 

HWND hwndParent; 

WORD winitParml, winitParm2; 

/* Allocate a global memory object for the dialog box template. */ 


hglbDlgTemp = GlobalAlloc(GHND, TEMPLATE_SIZE); 
. /* Build a DLGTEMPLATE structure in the memory object. */ 


digprc = (DLGPROC) MakeProcInstance(DialogProc, hinst); 
result = DialogBoxIndirectParam(hinst, hglbDlgTemp, hwndParent, 
digprc, (LPARAM) MAKELONG(wInitParml, wInitParm2)); 


DialogBox, DialogBoxIndirect, DialogBoxParam, DialogProc, EndDialog, 
MakeProclInstance 


ram | 


int DialogBoxParam(hinst, lpszDigTemp, hwndOwner, dlgprc, |[ParamlInit) 


HINSTANCE hinst; /* handle of application instance */ 
LPCSTR IpszDlgTemp; /* address of dialog box template name st 
HWND hwndOwner; /* handle of owner window */ 
DLGPROC digprc; /* instance address of dialog box procedure i 
LPARAM /Paramlnit; * /* imitialization value sa | 


The DialogBoxParam function creates a modal dialog box from a dialog box tem- 


Parameters 


plate resource. Before displaying the dialog box, the function passes an applica- 
tion-specified value to the dialog box procedure as the /Param parameter of the 
WM_INITDIALOG message. An application can use this value to initialize dialog 

box controls. | 


hinst 7 | 
Identifies an instance of the module whose executable file contains the dialog 
box template. | 


lpszDlgTemp : | 
Points to a null-terminated string that names the dialog box template. 


hwndOwner | 
Identifies the window that owns the dialog box. 


Return Value 


Comments | 


Example 


See Also 
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dlgpre 
Specifies the procedure-instance address of the dialog box procedure. The 
address must be created by using the MakeProclInstance function. For more in- 
formation about the dialog box procedure, see the description of the Dialog- 
Proc callback function. 


IParamInit- 
Specifies a 32-bit value that DialogBoxParam passes to the dialog box proce- 
dure when creating the dialog box. 


The return value specifies the value of the nResult parameter specified in the End- 
Dialog function that is used to terminate the dialog box. The system processes 
values returned by the dialog box procedure and does not return them to the appli- 
cation. The return value is —1 if the function cannot create the dialog box. 


The CreateWindowEx function is called to create the dialog box. The dialog box 
procedure then receives a WM_SETFONT message (if DS_SETFONT style was 
specified) and a WM_INITDIALOG message, and then the dialog box is dis- — 
played. 


The DialogBoxParam function does not return control until the dialog box proce- 


dure terminates the modal dialog box by calling the EndDialog function. 


~ A dialog box can contain up to 255 controls. 


The following example uses the DialogBoxParam function to create a modal 
dialog box. The function passes the dialog box a pointer to a string when the 
WM_INITDIALOG message is being processed. 


DLGPROC dlgprc; 
HWND hwndParent; 
PSTR pszFileName; 
int result; 


case IDM_OPEN: 


digprc = (DLGPROC) MakeProcInstance(FileOpenProc, hinst); 

result = DialogBoxParam(hinst, "FileOpenBox", hwndParent, 
digprc, MAKELPARAM(pszFileName, 80); 

Freekrocinstance( ( FARPROC) digprc); 

break; : 


: DialogBox, DialogBoxIndirect, DialogBoxindirectParam, DialogProc, — 


earns MakeProcInstance 
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DialogProc [2x | 


BOOL CALLBACK DialogProc(hwndDlg, msg, wParam, lParam) 


HWND hwndDie; /* handle of dialog box | 
UINT msg; /* message i 
WPARAM wParam; /* first message parameter */ 
LPARAM /Param; /* second message parameter si 


The DialogProc function is an application-defined callback function that 
processes messages sent to a modeless dialog box. 


Parameters hwndDlg 
Identifies the dialog box. 


msg 
Specifies the message. 


wParam | 
Specifies 16 bits of additional message-dependent information. 


lParam 
Specifies 32 bits of additional message-dependent information. 


Return Value Except in response to the WM_INITDIALOG message, the dialog box procedure 
should return nonzero if it processes the message, and zero if it does not. In re- 
sponse to a WM_INITDIALOG message, the dialog box procedure should return 
zero if it calls the SetFocus function to set the focus to one of the controls in the 
dialog box. Otherwise, it should return nonzero, in which case the system will set 
the focus to the first control in the dialog box that can be given the focus. 


Comments The dialog box procedure is used only if the dialog box class is used for the dialog 
box. This is the default class and is used if no explicit class is given in the dialog 
box template. Although the dialog box procedure is similar to a window proce- 
dure, it must not call the DefWindowProc function to process unwanted mes- 
sages. Unwanted messages are processed internally by the dialog box window 
procedure. 


DialogProc is a placeholder for the application-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the applica- 
tion’s module-definition file. 


See Also CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, Create- 
DialogParam, DefWindowProc, SetFocus 
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DirectedYield its Leer 


void Directed Yield(htask) 


HTASK htask; | 
nate Directed Yield function puts the current task to yi and cares the given 
as 
Parameters htask 
-__. Specifies the task to be executed. 
Return Value This function does not return a value. 
Comments | When relinquishing control to other applications Ghat is when exiting hard mode), 


a Windows-based debugger should call Directed Yield, identifying the handle of 
the task being debugged. This ensures that the debugged application runs next and 
that messages received during debugging are processed by the appropriate win- 
dows. 


The Windows scheduler executes a task only when there is an event waiting for it, 
such as a paint message, or a message posted in the message queue. 


If an application uses Directed Yield for a task with no events scheduled, the task 
will not be executed. Instead, Windows searches the task queue. In some cases, 
however, you may want the application to force a specific task to be scheduled. 
The application can do this by calling the PostAppMessage function, specifying a 
WM_NULL message identifier. Then, when the application calls Directed Yield, . 
the scheduler will run the task regardless of the task’s event status. a 


Directed Yield starts the task identified by htask at the location where it left off. 
Typically, debuggers should use TaskSwitch instead of Directed Yield, because 
TaskSwitch can Start a task at any address. 


Directed Yield returns when the current task is rgawakened: This occurs when the 
task identified by htask waits for messages or uses the Yield or paar gte . 
| function. Execution will continue as before the task switch. ae 


Directed Yield is located in KRNL286.EXE and KRNL3 86. EXE and is available 
in Windows versions 3.0 and 3.1. 


See Also -—_—~PostAppMessage, TaskSwitch, TaskGetCSIP, TaskSetCSIP, Yield 
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DispatchMessage [ 2.x | 


LONG DispatchMessage(/pmsg) | 
const MSG FAR* Ipmsg; /* address of structure with message */ 


The DispatchMessage function dispatches a message to a window. It is typically 
used to dispatch a message retrieved by the GetMessage function. 


Parameters Ipmsg — 
Points to an MSG structure that contains the message. The MSG structure has 
the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


The MSG structure must contain valid message values. If the Ipmsg parameter 
points toa WM_TIMER message and the /Param parameter of the 
WM_TIMER message is not NULL, then /Param points to a function that is 
called instead of the window procedure. 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value | The return value specifies the value returned by the window procedure. Although 
its meaning depends on the message being dispatched, generally the return value is 
ignored. 


Example The following example shows a typical use of the DispatchMessage function in 
an application’s main message loop: . 


MSG msg; 

HWND hwnd; 

HWND hwndDigModeless; 
HANDLE haccl; 


while (GetMessage(&msg, NULL, @, @)) { 
if (ChwndDlgModeless == NULL || 
!IsDialogMessage(hwndDlgModeless, &msg)) && 
!TranslateAccelerator(hwnd, haccl, &msg)) { 
TranslateMessage(&msg); 
DispatchMessage(&msqg) ; 


i See Also 


DigDirList 
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GetMessage, PeekMessage, PostAppMessage, PostMessage, TranslateMessage 


[2x | 


int DlgDirList(hwndDlg, lpszPath, idListBox, idStaticPath, uFileType) 


HWND hwndDieg; 
LPSTR [pszPath; 
int idListBox; 

int idStaticPath; 
UINT uFileType; 


Parameters 


/* handle of dialog box with list box */ 
/* address of path or filename string os 
/* identifier of list box a | 
/* identifier of static control : */ 
/* file attributes to display i 


~ The DigDirList function fills a list box with a file or directory listing: It fills the 


list box with the names of all files matching the specified path or filename. 


hwndDlg | 
Identifies the dialog box that contains the list box. 


lpszPath 
Points to a null-terminated string that contains the path or filename. DigDirList 
modifies this string, which should be long enough to contain the modifications. 
For more information, see the following Comments section. 


idListBox | 7 
Specifies the identifier of a list box. If this parameter 1S Zero, DigDirList a as- 
sumes that no list box exists and does not attempt to fill one. 


idStaticPath 
Specifies the identifier of the static control used for displaying the current drive 
and directory. If this parameter is zero, DlgDirList assumes that no such con- 
trol is present. | | 


uF ileType - 
Specifies the attributes of the filenames to be displayed. This parameter can be 
a combination of the following values: 


Value Meaning 


DDL_READWRITE Read-write data files with no additional attributes. 
‘DDL_READONLY _Read-onlyfiles. 
DDL_HIDDEN ‘Hidden files. 

DDL_SYSTEM : System files. 

DDL_DIRECTORY Directories. — 

DDL_ARCHIVE Archives. 
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Return Value 


Comments 


| See Also 


Value Meaning 


DDL_POSTMSGS LB_DIR flag. If the LB_DIR flag is set, Windows places 
the messages generated by DigDirList in the application’s 
queue; otherwise, they are sent directly to the dialog box 
procedure. 

DDL_DRIVES Drives. 

DDL_EXCLUSIVE Exclusive bit. If the exclusive bit is set, only files of the 
specified type are listed; otherwise, files of the specified 
type are listed in addition to normal files. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


If you specify a zero-length string for the [pszPath parameter or if you specify 
only a directory name but do not include any filename, the string will be changed 
Ko Bear 


The DigDirList function shows directories enclosed in brackets ([ ]) and shows 
drives in the form [-x-], where x is the drive letter. | 


The /pszPath parameter has the following form: 
[drive:][[\ldirectory|\directory]...\][filename] 


In this example, drive is a drive letter, directory is a valid MS-DOS directory 
name, and filename is a valid MS-DOS filename that must contain at least one 
wildcard. The wildcards are a question mark (?), meaning match any character, 
and an asterisk (*), meaning match any number of characters. 


If the [pszPath parameter includes a drive or directory name, or both, the current 
drive and directory are changed to the specified drive and directory before the list 
box is filled. The static control identified by the idStaticPath parameter is also up- 
dated with the new drive or directory name, or both. 


_ After the list box is filled, IpszPath is updated by removing the drive or directory 


portion, or both, of the path and filename. 
DigDirList sends LB_LRESETCONTENT and LB_DIR messages to the list box. 


DigDirListComboBox, DlgDirSelect, DlgDirSelectComboBox 
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DigDirListComboBox 


int DigDirListComboBox(hwndDilg, lpszPath, idComboBox, idStaticPath, uFileType) 
HWND hwndDig; /* handle of dialog box with combo box sa 


LPSTR [pszPath; /* address of path or filename string *} 
int idComboBox; /* identifier of combo box | */ 
int idStaticPath; /* identifier of static control */ 
UINT uFileType; /* file attributes to display 7 */ 


The DigDirListComboBox function fills the list box of a combo box with a file or 
directory listing. It fills the list box with the names of all files matching the 
specified path and filename. 


Parameters hwndDlg 
Identifies the dialog box that contains the combo box. 


[pszPath 
Points to a null-terminated string that contains the path and filename. For more 
information, see the following Comments section. 


idComboBox | 
Specifies the identifier of a BouIbG box ina dialog box. If this parameter is Zero, 
Dig DU MASC OMDOnOX assumes that no Eompe box exists and does not attempt 
to fill one. | 


idStaticPath — | 
Specifies the identifier of ihe static control used for displaying the current drive 
and directory. If this parameter is zero, DigDirListComboBox assumes that no 
such control is present. 

uFileType 
Specifies the attributes of the filenames to be displayed. This parameter can be 
a combination of the following values: 


- Value : Meaning 


DDL_READWRITE Read-write data files with no additional attributes. 
DDL_READONLY Read-only files. 


DDL_HIDDEN Hidden files. 
DDL_SYSTEM System files. 
DDL_DIRECTORY Directories. 
DDL_ARCHIVE — Archives. 


DDL_POSTMSGS CB_DIR flag. If the CB_DIR flag is set, Windows places 
we _ the messages generated by DigDirListComboBox in the 
application’s queue; otherwise, they are sent directly to the 
dialog box procedure. 


DDL_DRIVES _ Drives. 
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Return Value 


Comments 


See Also 


DigDirSelect 


Value Meaning 


DDL_EXCLUSIVE Exclusive bit. If the exclusive bit is set, only files of the 
_ specified type are listed; otherwise, files of the specified 
type are listed in addition to normal files. | 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The DigDirListComboBox function shows directories enclosed in brackets ([ ]) 
and shows drives in the form [-x-], where x is the drive letter. 


The /pszPath parameter has the following form: 
[drive:][[\ldirectory|\directory]...\][filename] 


In this example, drive is a drive letter, directory is a valid MS-DOS directory 
name, and filename is a valid MS-DOS filename that must contain at least one 
wildcard. The wildcards are a question mark (?), meaning match any character, 
and an asterisk (*), meaning match any number of characters. 


If the /pszPath parameter includes a drive or directory name, or both, the current 
drive and directory are changed to the specified drive and directory before the list 
box is filled. The static control identified by the idStaticPath parameter is also up- 
dated with the new drive or directory name, or both. 


After the list box of the combo box is filled, IpszPath is updated by removing the 


drive or directory portion, or both, of the path and filename. 


DigDirListComboBox sends CB_RESETCONTENT and CB_DIR messages to 
the combo box. 


DigDirList, DigDirSelect, DigDirSelectComboBox 


BOOL DigDirSelect(hwndDlg, IpszPath, idListBox) 


HWND hwndDig; 
LPSTR [pszPath; _ 
int idListBox; 


/* handle of dialog box with list box a Rh 


/* address of buffer for path or filename string ia | 
/* identifier of listbox | | 


The DigDirSelect function retrieves the current selection from a list box. It as- 
sumes that the list box has been filled by the DlgDirList function and that the 
selection is a drive letter, a file, or a directory name. 
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Parameters hwndDlg 
Identifies the dialog box that contains the list box. 


[pszPath 
Points to a 128-byte buffer for the path or filename. 


idListBox 
Specifies the integer identifier of a list box in the dialog box. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments If the current selection is a directory name or drive letter, DigDirSelect removes 
the enclosing brackets (and hyphens, for drive letters) so that the name or letter is 
ready to be inserted into a new path or filename. If there is no selection, the con- 
tents of the buffer pointed to by the /pszPath parameter do not change. 


The DigDirSelect function does not allow more than one filename to be returned 
from a list box. 


The list box must not be a multiple-selection list box. If it is, this function will not 
return a zero value and /pszPath will remain unchanged. 


DigDirSelect sends LB_GETCURSEL and LB_GETTEXT messages to the list 
box. 


- See Also DigDirList, DlgDirListComboBox, DigDirSelectComboBox, DigDirSelectEx — 


DigDirSelectComboBox 


BOOL DigDirSelectComboBox(hwndDlg, lpszPath, idComboBox) 


HWND hwndD!g; /* handle of dialog box with list box +) 
-LPSTR /pszPath; /* address of buffer for path or filename string —= */ 
int idComboBox; /* identifier of combo box */ 


The DigDirSelectComboBox function retrieves the current selection from the list 
box of a combo box. It assumes that the list box has been filled by the DigDirList- 
ComboBox function and that the selection is a drive letter, a file, or a directory 
name. 


Parameters hwndDleg 
| Identifies the dialog box that contains the combo box. 


lpszPath — 
Points to.a 128- Bs buffer for the path or ieaaanes | 
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idComboBox 
Specifies the integer identifier of the combo box in the dialog box. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments _ The DigDirSelectComboBox function does not allow more than one selection to 


be returned from a combo box. 


" If the current selection is a directory name or drive letter, DigDirSelect- 
ComboBox removes the enclosing brackets (and hyphens, for drive letters) so that 
the name or letter is ready to be inserted into a new path or filename. If there is no 
selection, the contents of buffer pouited to by the /pszPath parameter do not 
change. 


DigDirSelectComboBox sends CB_GETCURSEL and CB_GETLBTEXT mes- 
sages to the combo box. 


See Also | DigDirList, DigDirListComboBox, DigDirSelect, DigDirSelectComboBoxEx, 
DigDirSelectEx 


DigDirSelectComboBoxEx ‘a 


BOOL DigDirSelectComboBoxEx(hwndDlg, lpszPath, cbPath, idComboBox) 
HWND hwndDig; /* handle of dialog box with list box st 


LPSTR [pszPath; /* address of buffer for path string */ 
int cbPath; /* number of bytes in path string a) 
int idComboBox; /* identifier of combo box */ 


The DigDirSelectComboBoxEx function retrieves the current selection from the | 
list box of a combo box. The list box should have been filled by the DigDirList- 
ComboBox function, and the selection should be a drive letter, afile,ora 
directory name. 


Parameters hwndDlg 
i Identifies the dialog box that contains the combo box. 
IpszPath | 
Points to a buffer that receives the selected atti or filename. 
cbPath 


Specifies the length, in bytes, of the path or filename pointed to by the [pszPath 
parameter. This value should not be larger than 128. 


idComboBox 
Specifies the integer identifier of the combo box in the dialog box. 


Return Value 


Comments 


See Also 
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The return value is nonzero if the current combo box selection is a directory name. 
Otherwise, it is zero. 


The DigDirSelectComboBoxEx function does not allow more than one filename 
to be returned from a combo box. 


If the current selection is a directory name or drive letter, DigDirSelect- 
ComboBoxEx removes the enclosing square brackets (and hyphens, for drive let- 
ters) so that the name or letter is ready to be inserted into a new path or filename. 
If there is no selection, the contents of buffer pointed to by the /pszPath parameter 


do not change. 


DigDirSelectComboBoxEx sends CB_GETCURSEL and CB_GETLBTEXT 
messages to the combo box. 


DigDirList, DigDirListComboBox, DigDirSelect, DigDirSelectEx, 
DigDirSelectComboBox 


DigDirSelectEx ae 


~ BOOL DilgDirSelectEx(hwndDlg, lpszPath, cbPath, idListBox) 


HWND hwnadDig; 
LPSTR [pszPath; 
int cbPath; 

int idListBox; 


Parameters 


Return Value 


/* handle of dialog box with list box #} 


/* address of buffer for path string #/ 
/* number of bytes in path string **/ 
/* identifier of list box | | 


The DigDirSelectEx function retrieves the current selection from a list box. The | 
specified list box should have been filled by the DigDirList function, and the 
selection should be a drive letter, a file, or a directory name. 


hwndDlg 
Identifies the dialog box that contains the list box. 
lpszPath 
Points to a buffer that receives the selected ee or filename. 
cbPath 


Specifies the length, in oe of the path or filename pomlew to by the © IpsePath 
parameter. This value should not be larger than 128. 


AidListBox 


Specifies the integer identifier of a list box in the dialog box. 


The return value is nonzero if the current list box selection 1 is a directory name. 
Otherwise, it is zero. 
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Comments If the current selection is a directory name or drive letter, DigDirSelectEx re- 
moves the enclosing square brackets (and hyphens, for drive letters) so that the 
name or letter is ready to be inserted into a new path or filename. If there is no 
selection, the contents of buffer pounce to by the /pszPath parameter do not. 
change. 


The DigDirSelectEx function does not allow more than one filename to be re- 
turned from a list box. : 


The list box must not be a multiple-selection list box. If it 1s, this function will not 
return a zero value and /pszPath will remain unchanged. 


DigDirSelectEx sends LB_GETCURSEL and LB_GETTEXT messages to the list 
box. 


See Also DigDirList, DigDirListComboBox, DlgDirSelect, DigDirSelectComboBox 


DOS3Call 


The DOS3Call function allows an application to call an MS-DOS Interrupt 21h 
function. DOS3Call can be called only from assembly-language routines. It is ex- 
ported from KRNL286.EXE and KRNL386.EXE and is not defined in any Win- | 
dows header or include files. = 


Parameters Registers must be set up as required by the desired Interrupt 21h function before — 
the application calls the DOS3Call function. — 


Return Value The register contents are preserved as they are returned by the Interrupt 21h func- 
| tion. | 
Comments Applications should use this function instead of a directly coded MS-DOS Inter- 


rupt 21h function. The DOS3Call function runs somewhat faster than the equiv- 
alent MS-DOS Interrupt 21h function running in Windows. 
Example The following example shows how to prototype the DOS3Call function in C: 
| extern void FAR PASCAL DOS3Call(void); 


To declare the DOS3Call function in an assembly- language routine, an applica- 
tion could use the following line: | 


extrn DOS3CALL: far 
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If the application includes CMACROS.INC, the function is declared as follows: 
extrnFP D0S3Call | 


The following example is a typical use of the DOS3Call function: 


extrn DOS3CALL: far 


> set registers 


mov ah, DOSFUNC sDOSFUNC = Int 21h function number 
cCall DOS3Cal] 


DPtoLP - 


_ BOOL DPtoLP (hdc, [ppt, cPoints) 


HDC hdc; /* handle of device context **/ 
POINT FAR* [ppt; /* address of array with points ss 
int cPoints; _/* number of points in array */ 


The DPtoLP function converts device coordinates (points) into logical coordinates. 


Parameters hdc 
Identifies the device context. 


lppt 
Points to an array of POINT structures. Each coordinate in each structure is 
mapped into the logical coordinate system for the current device context. The — 
POINT structure has the following form: 
typedef struct tagPOINT { /* pt */ 
int x; 
int y; 
} POINT; 


For a full description of this structure, see the M oe Windows Program- 
mer’s Reference, Volume 3. , 


cPoints 
Specifies the number of points in the array. 


Return Value _ The return value is nonzero if the function is successful. Otherwise, it is zero. 
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Comments The conversion depends on the current mapping mode and the settings of the 
Origins and extents for the device’s window and viewport. 


Example The following example sets the mapping mode to MM_LOENGLISH, and then 
7 calls the DPtoLP function to convert the coordinates of a rectangle into logical 
coordinates: 


RECT rc; 


SetMapMode(hdc, MM_LOENGLISH); 
SetRect(&rc, 100, 100, 200, 200); 
DPtoLP(hdc, (LPPOINT) &rc, 2); 


See Also LPtoDP 


DragAccepiFiles [31 | 
include <shellapi.h> | 
void DragAcceptFiles(hwnd, fAccept) 


-HWND hwnd; /* handle of the registering window */ 
BOOL fAccept; /* flag for whether dropped files are accepted i 
The DragAcceptFiles function registers whether a given window accepts dropped 
files. 
Parameters hwnd - 
Identifies the window registering whether it accepts dropped files. 
fAccept 


Specifies whether the window specified by the hwnd parameter accepts 
dropped files. An application should set this value to TRUE to accept dropped 
files or FALSE to discontinue accepting dropped files. 


Return Value This function does not return a value. 
Comments | _ When an application calls DragAcceptFiles with fAccept set to TRUE, Windows 


File Manager (WINFILE.EXE) sends the specified window a WM_DROPFILES 
message each time the user drops a file in that window. | 


DragFinish 
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[3.1 | 


#include <shellapi.h> 


void DragFinish(hDrop) 


HDROP hDrop; 


Parameters 


Return Value 


/* handle of memory to free **/ 


The DragFinish function reieaes memory ‘that Windows allocated for use in 
transferring filenames to the application. | 


hDrop 
Identifies the internal data structure that describes droped files. This handle is 
passed to the application in the wParam parameter of the WM_DROPFILES 
message. 


This function does not return a value. 


DragQueryFile pg Saree pe ee err 


-_#include <shellapi.h> 


UINT DragQueryFile(hDrop, iFile, eek ile, cb) aes 

HDROP hDrop; /* handle of structure for dropped files Bay pa 

UINT iFile; _ /* index of file to query _ ae 

LPSTR I[pszFile; /* address of buffer for returned filename **/ 

UINT cb; /* size of buffer for filename - =) 
The DragQueryFile function retrieves the number of stopped files and their | 
filenames. | 

Parameters hDrop 


Identifies the internal data structure containing filenames for the dropped files. 
This handle is passed to the application in the wParam parameter of the 
WM —~DROPFILES message. 


iFile 
Specifies the index of the file to query. The index of the first file is 0. If the | 
_ value of the iFile parameter is -1, DragQueryFile returns the number of files 
_ dropped. If the value of the iFile parameter is between zero and the total num-_ 
ber of files dropped, DragQueryFile copies the filename corresponding to that 


eo value to the buffer pointed to by the /pszF ile orci 
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Return Value 


See Also 


DragQueryPoint 


lpszFile 
Points to a null-terminated string that contains the filename of a dropped file 
when the function returns. If this parameter is NULL and the iFile parameter 
specifies the index for the name of a dropped file, DragQueryFile returns the 
required size, in bytes, of the buffer for that filename. 


cb 
Specifies the size, in bytes, of the lpszFile buffer. 


When the function copies a filename to the /pszFile buffer, the return value is the 
number of bytes copied. If the iFile parameter is OXFFFF, the return value is the 
number of dropped files. If iFile is between zero and the total number of dropped 
files and if lpszFile is NULL, the return value is the required size of the /pszFile 
buffer. | 


DragQueryPoint 


#include <shellapi.h> 
BOOL DragQueryPoint(hDrop, Ippt) 


HDROP hDrop; 
POINT FAR®* [ppt; 


Parameters 


/* handle of structure for dropped file */ 
/* address of structure for cursor coordinates */ 


The DragQueryPoint function retrieves the window coordinates of the cursor 
when a file is dropped. | 
hDrop 
Identifies the internal data structure that describes the dropped file. This struc- 
ture is returned in the wParam parameter of the WM_DROPFILES message. 


lppt 
Points to a POINT structure that the function fills with the coordinates of the 
position at which the cursor was located when the file was dropped. The 
POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
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Return Value The return value is nonzero if the file is dropped in the client area of the window. 
Otherwise, it is Zero. 


Comments The DrasQueryPoint function fills the POINT structure with the coordinates of 
the position at which the cursor was located when the user released the left mouse 
button. The window for which coordinates are returned is the window that re- 
ceived the WM_DROPFILES message. . 


See Also DragQueryFile 


-DrawFocusRect Bo 


void DrawFocusRect(hdc, lprc) eu, 
HDC hdc; /* handle of device context */ 
const RECT FAR® [prc; /* address of structure with rectangle st 


The DrawFocusRect function draws a rectangle in the style used to indicate that 
the rectangle has the focus. 


_ Parameters hdc | 

Identifies the device context. 
Ipre i 
Points to a RECT structure that contains the logical coordinates of the — 
rectangle. The RECT structure has the following form: _ 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT 


Fora full description of this structure, see the M icrosoft Was Program- 
mer’ § Reference, Volume 3. 


ReturnValue  =——‘ This function does not return a value. 


Comments | Because this’ is an XOR function, calling it a second time and specifying the same 
| Feclan ere removes the rectangle from the screen. 
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The rectangle this function draws cannot be scrolled. To scroll an area containing 
a rectangle drawn by this function, call DrawFocusRect to remove the rectangle 
from the screen, scroll the area, and then call DrawFocusRect to draw the 
rectangle in the new position. 


See Also FrameRect 


Drawlicon | Pax] 


BOOL DrawlIcon(hdc, x, y, hicon) 


HDC hdc; /* handle of device context * / 
int x; /* x-coordinate of upper-left corner | 
int y; /* y-coordinate of upper-left corner | 
HICON hicon; /* handle of icon to draw * / 


The DrawlIcon function draws an icon on the given device. The DrawlIcon func- 
tion places the icon’s upper-left corner at the specified location. 


Parameters — hdc 
Identifies the device context for a window. 


x 
Specifies the logical x-coordinate of the upper-left corner of the icon. 


Specifies the logical y-coordinate of the upper-left corner of the icon. 


hicon 
Identifies the icon to be drawn. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The icon resource must have been loaded by using the LoadIcon function. The 
| MM_TEXT mapping mode must be selected before using this function. 


See Also | GetMapMode, LoadIcon, SetMapMode 
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DrawMenuBar — ca ri 


void DrawMenuBar(iwnd) 


HWND hwnd; 


Parameters 


Return Value 


DrawText 


hwnd 


/* handle of window with menu bar to redraw **/ 


The DrawMenuBar function redraws the menu bar of the given window. If a 
menu bar is changed after Windows has created the window, an application should 
call this function to draw the changed menu bar. - 


Identifies the window whose menu must be redrawn. 


This function does not return a value. 


int DrawText(hdc, lpsz, cb, lprc, fuFormat) 


HDC hdc; 
LPCSTR /psz; 

int cb; 

RECT FAR® [prc; 
UINT fuFormat; 


Parameters 


/* handle of device context | : **/ 
/* address of string to draw , ey) BGP 
/* string length */ 
_. /* address of structure with formatting dimensions  =—_ */ 
/* text-drawing flags al 


The DrawText function draws formatted text into a given rectangle. It formats 
text by expanding tabs into appropriate spaces, aligning text to the left, right, or — 
center of the rectangle, and breaking text into lines that fit within the rectangle. 


The DrawText function uses the device context’s selected font, text color, and 
background color to draw the text. Unless the DT_NOCLIP format is specified, 
DrawText clips the text so that the text does not appear outside the given 
rectangle. All formatting is assumed to have multiple lines unless the 
DT_SINGLELINE format is specified. 


| Identifies the device context. This cannot be a metafile device context. 


[psz : | | | 
Points to the tring to be drawn. If the cb parameter i is —l1, the string must be | 
null- terminated. | | | 
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cb 
Specifies the number of bytes in the string. If this parameter is —1, then the Ipsz 
parameter is assumed to be a long pointer to a null-terminated string and 
DrawText computes the character count automatically. 


lpre | 
Points to a RECT structure that contains the logical coordinates of the upper- 
left and lower-right corners of the rectangle in which the text is to be formatted. 
The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


fuFormat 
Specifies an array of flags that determine how to draw the text. This parameter 
can be a combination of the following values: 


Value Meaning | 

DT_BOTTOM Specifies bottom-aligned text. This value must be 
combined with DT_SINGLELINE. 

DT_CALCRECT Determines the width and height of the rectangle. 


If there are multiple lines of text, DrawText will 
use the width of the rectangle pointed to by the 
Iprc parameter and extend the base of the rectangle 
to bound the last line of text. If there is only one 
line of text, DrawText will modify the right side 
of the rectangle so that it bounds the last character 
in the line. In either case, DrawText returns the 
height of the formatted text but does not draw the 


text. 
DT_CENTER | Centers text horizontally. 
DT_EXPANDTABS Expands tab characters. The default number of 


characters per tab is eight. 


DT_EXTERNALLEADING Includes the font external leading in line height. 
| Normally, external leading is not included in the 


height of a line of text. 
DT_LEFT Left-aligns text. 
DT_NOCLIP Draws without clipping. DrawText is somewhat 


faster when DT_NOCLIP is used. 


Return Value 


| Comments 


See Also — 
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Value Meaning 


DT_NOPREFIX Turns off processing of prefix characters. Nor- 
mally, DrawText interprets the mnemonic & as a 
directive to underscore the character that follows, 
and the mnemonic && as a directive to print a 
single &. By specifying DT_NOPREFIX, this pro- 
cessing is turned off. 


DT_RIGHT | Right-aligns text. 

DT_SINGLELINE Specifies single line only. Carriage returns and 
linefeeds do not break the line. 

DT_TABSTOP Sets tab stops. The high-order byte of the 


fuFormat parameter is the number of characters 
for each tab. The default number of characters per 


tab is eight. 
DT_TOP Specifies top-aligned text Gilets line only). 
DT_VCENTER Specifies vertically centered text (single line only). 


DT_WORDBREAK Specifies word breaking. Lines are automatically 
+ broken between words if a word would extend past 
the edge of the rectangle specified by the Iprc pa- 
_ rameter. A carriage return—linefeed sequence will 
also break the line. 


Note that the DT _CALCRECT, DT _ EXTERNALLEADING, | 
DT_INTERNAL, DT _NOCLIP, and DT_N OPREFIX values cannot be used 
with the DT _TABSTOP value. a 


The return value specifies the height of the text if the function is successful. 


If the selected font is too large for the specified rectangle, the DrawText function 
does not attempt to substitute a smaller font. 


If the DT_CALCRECT flag is specified, the RECT structure pointed to by the | 
lpre parameter will be updated to reflect the width and height needed to draw the 
text. 


If the TA_UPDATECP text-alignment flag has been set (see the SetTextAlign 
function), DrawText will display text starting at the current position, rather 
than at the left of the given rectangle. DrawText will not wrap text when the 
TA_UPDATECP flag has been set (the DT_WORDBREAK flag will have no 


effect). 


The text color must be set by the SetTextColor function. 


_ ExtTextOut, SetTextColor, TabbedTextOut, TextOut 
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DriverProc _ [3.1 | 


LRESULT CALLBACK DriverProc(dwDriverldentifier, hDriver, wMessage, [Paraml, lParam2) 


DWORD dwDriverldentifier; /* identifies installable driver sf 
HDRVR Driver; /* handle of installable driver a 
UINT wMessage; | /* message */ 
LPARAM /Param1; _ /* first message parameter si 
LPARAM /Param2; /* second message parameter aij 


The DriverProc function processes the specified message. 


Parameters dwDriverldentifier 
Specifies an identifier of the installable driver. 


hDriver | 
Identifies the installable driver. This parameter is a unique handle that Win- 
dows assigns to the driver. 


wMessage 
Identifies a message that the driver must process. Following are the messages 
that Windows or an application can send to an installable driver: 


Message Description 


DRV_CLOSE Notifies the driver that it should decrement 
(decrease by one) its usage count and unload the 
driver if the count is zero. 


DRV_CONFIGURE Notifies the driver that it should display a custom- 
configuration dialog box. (This message should be 
sent only if the driver returns a nonzero value 
when the DRV_QUERYCONFIGURE message is 
processed.) 


DRV_DISABLE Notifies the driver that its allocated memory is 
' about to be freed. 
DRV_ENABLE Notifies the driver that it has been loaded or re- 
loaded, or that Windows has been enabled. 
DRV_FREE | Notifies the driver that it will be discarded. 
DRV_INSTALL — Notifies the driver that it has been successfully in- 
: stalled. 
DRV_LOAD Notifies the driver that it has been successfully 
loaded. 
DRV_OPEN Notifies the driver that it is about to be opened. 


DRV_POWER Notifies the driver that the device’s power source 
is about to be turned off or turned on. : 
DRV_QUERY CONFIGURE Determines whether the driver supports the 
| DRV_CONFIGURE message. The message dis- 
plays a private configuration dialog box. 


Return Value 


Comments 


See Also 


Ellipse 
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Message Description 


DRV_REMOVE Notifies the driver that it is about to be removed 
from the system. 


[Param 
Specifies the first message parameter. 


— [Param2 


Specifies the second. message parameter. 
The return value is nonzero if the function is successful. Otherwise, it is zero. 


The DriverProc function is the main function within a Windows installable 


driver; it is supplied by the driver developer. 


When the wMessage parameter is DRV_OPEN, /Param1 is the string following 
the driver filename from the SYSTEM_INI file and lParam? is the value given as 
the /Param parameter in the call to the OpenDriver function. 


When the wMessage parameter is DRV_CLOSE, /ParamI and [Param2 are the . 
same values as the /Param/ and [Param2 parameters in the call to the Close- 
Driver function. 


CloseDriver, OpenDriver 


BOOL Ellipse(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect) 


HDC hdc; 

int nLeftRect; 
int nTopRect; 
int nRightRect; 
int nBottomRect; 


Parameters 


/* handle of device context ae 
/* x-coordinate upper-left corner bounding rectangle a 
/* y-coordinate upper-left corner bounding rectangle | 
/* x-coordinate lower-right corner bounding rectangle i 
/* y-coordinate lower-right corner bounding rectangle ha 


The Ellipse function draws an ellipse. The center of the ellipse is the center of the 
specified bounding rectangle. The ellipse is drawn by using the current pen, and its 
interior is filled by using the current brush. _ 


If either the width or the height of the bounding rectangle is zero, the function 
does not draw the ellipse. . 


hdc 
Identifies the device context. 
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nLeftRect | 
Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle. 


nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the bounding 
rectangle. 


nRightRect 
Specifies the logical x-coordinate of the jo ersieht corner of the bounding 
rectangle. 


nBottomRect 
Specifies the logical y-coordinate of the lower-right c corner of the bounding 
rectangle. 


Return Value _ The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The figure drawn by this function extends up to but does not include the right and 
bottom coordinates. This means that the height of the figure is determined as fol- 
lows: 
nBottomRect — nTopRect 
Similarly, the width of the figure 1 is determined as follows: 


nRightRect — nLeftRect 


Both the width and the height of a rectangle must be greater than 2 units and less 
than 32,767 units. 


See Also ~ Are, Chord 


EmptyClipboard — [ex] 
BOOL EmptyClipboard(void) 


The EmptyClipboard function empties the clipboard and frees handles to data in 
_the clipboard. It then assigns ownership of the clipboard to the window that cur- 
rently has the clipboard open. 
Parameters This function has no parameters. 


Return Value ~The return value is nonzero if the function is successful. Otherwise, it is zero. 
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Comments The clipboard must be open when the EmptyClipboard function is called. 


See Also ~ OpenClipboard 


EnableCommNotification _ EXE 


BOOL EnableCommNotification(idComDev, hwnd, cbWriteNotify, chOutQueue) 


int idComDev; /* communications-device identifier sd 
HWND hwnd; /* handle of window receiving messages ay 
int cbWriteNotify; /* number of bytes written before notification a 
int chOutQueue; /* minimum number of bytes in output queue aera 


The EnableCommNotification function enables or disables 
WM_COMMNOTIPY message posting to the given window. | 


Parameters idComDev 
| Specifies the communications device that is posting notification messages to 
the window identified by the hwnd parameter. The OpenComm function re- 
turns the value for the idComDev parameter. 


hwnd o 
Identifies the window whose WM_COMMNOTIFY message posting will be 
enabled or disabled. If this parameter is NULL, EnableCommNotification dis- 
ables message posting to the current window. | 


cbWriteNotify 
Indicates the number of bytes the COM driver must write to the application’s 
input queue before sending a notification message. The message signals the ap- 
plication to read information from the input queue. 


cbOutQueue 
Indicates the minimum number of bytes in the output queue. When the number 
of bytes in the output queue falls below this number, the COM driver sends the 
application a notification message, signaling it to write information to the out- 


put queue. 

Return Value The return value is nonzero if the function is successful. Otherwise, it is zero, indi- 
cating an invalid COM port identifier, a port that is not open, or a function not sup- 
ported by COMM.DRV. 

Comments If an application specifies —1 for the cbWriteNotify parameter, the 


WM_COMMNOTIFY message is sent to the specified window for CN_EVENT 
and CN_TRANSMIT notifications but not for CN RECEIVE notifications. If —1 
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is specified for the cbOutQueue parameter, CN_EVENT and CN_RECEIVE noti- 
fications are sent but CN_TRANSMIT notifications are not. 


If a timeout occurs before as many bytes as specified by the cbWriteNotify parame- 
ter are written to the input queue, a WM_COMMNOTIFY message is sent with 
the CN_RECEIVE flag set. When this occurs, another message will not be sent 
until the number of bytes in the input queue falls below the number specified in 
the cbWriteNotify parameter. Similarly,a WM_COMMNOTIFY message in 
which the CN_RECEIVE flag is set is sent only when the output queue is larger 
than the number of bytes specified in the chOutQueue parameter. 


The Windows 3.0 version of COMM.DRV does not support this function. 


EnableHardwarelnput Ea 


BOOL EnableHardwareInput(/EnableInput) 


BOOL fEnableInput; —_—/* for enabling or disabling queuing */ 
The EnableHardwareInput function enables or disables queuing of mouse and 
keyboard input. 

Parameters fEnableInput 


Specifies whether to enable or disable queuing of input. If this parameter 1S 
TRUE, keyboard and mouse input are queued. If the parameter is FALSE, key- 
board and mouse input are disabled. 


Return Value _ The return pale is nonzero if queuing) of input was previously enabled. Other- 
| wise, it is zero. 


Comments | ~ This function does not disable input from installable drivers, nor does it disable 
device drivers. 


See Also GetInputState 
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EnableMenultem | [2x | 


BOOL EnableMenultem(hmenu, idEnableltem, uEnable) 


HMENU hmenu; /* handle of menu | */ 
UINT idEnableltem; /* menu-item identifier */ 
UINT uEnable; /* action flag =] 


The EnableMenultem function enables, disables, or grays (dims) a menu item. 


Parameters hmenu 
Identifies the menu. 


idEnableltem 
Specifies the menu item to be enabled, disabled, or grayed. This parameter can 
specify pop-up menu items as well as standard menu items. The interpretation 
of this parameter depends on the value of the uEnable parameter. : 


uEnable 
Specifies the action to take. This parameter can be MF_DISABLED, 
MF_ENABLED, or MF_GRAYED, combined with MF_BYCOMMAND or 
MF_BYPOSITION. These values have the following meanings: 


Value Meaning 


MF_BYCOMMAND Specifies that the idEnableltem parameter gives the menu- 
item identifier. 


MF_BYPOSITION Specifies that the idEnableltem parameter gives the posi- 
tion of the menu item (the first item is at position zero). 
MF_DISABLED | Specifies that the menu item is disabled. 
_ MF_ENABLED Specifies that the menu item is enabled. 
MF_GRAYED Specifies that the menu item is grayed. 
Return Value The return value is 0 if the menu item was previously disabled, 1 if the menu item 


was previously enabled, and —1 if the menu item does not exist. 


Comments To disable or enable input to a menu bar, see the WM_SYSCOMMAND message. 


The CreateMenu, InsertMenu, ModifyMenu, and LoadMenulIndirect func- 
tions can also set the state (enabled, disabled, or grayed) of a menu item. 


Using the MF_BYPOSITION value requires an application to specify the correct 
menu handle. If the menu handle of the menu bar is specified, a top-level menu 
item (an item in the menu bar) is affected. To set the state of an item in a pop-up 
or nested pop-up menu by position, an application must specify the handle of the 
pop-up menu. | 
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When an application specifies the MF_BYCOMMAND flag, Windows checks all 
pop-up menu items that are subordinate to the menu identified by the specified 
menu handle; therefore, unless duplicate menu items are present, specifying the 
menu handle of the menu bar is sufficient. 


See Also CheckMenultem, HiliteWMenultem 


EnableScrollBar ran] 


BOOL EnableScrollBar(hwnd, fnSBFlags, fuArrowFlags) 


HWND hwnd; /* handle of window or scroll bar */ 
int fnSBFlags; /* scroll-bar type flag *k/ 
UINT fuArrowFlags; /* scroll-bar arrow flag i 
The EnableScrollBar function enables or disables one or both arrows of a scroll 
bar. 
Parameters hwnd : 
Identifies a window or a scroll bar, depending on the value of the fnSBFlags pa- 
rameter. 
JnSBFlags 


Specifies the scroll bar type. This parameter can be one of the following values: 
Value Meaning 


SB_BOTH Enables or disables the arrows of the horizontal and vertical scroll 
bars associated with the given window. The hwnd parameter identi- 
fies the window. 

SB_CTL Identifies the scroll bar as a scroll bar control. The hwnd parameter 

| must identify a scroll bar control. 

SB_HORZ Enables or disables the arrows of the horizontal scroll bar associated 

with the given window. The hwnd parameter identifies the window. 


~SB_VERT Enables or disables the arrows of the vertical scroll bar associated 
_ with the given window. The hwnd parameter identifies the window. 


fuArrowFlags — | ° 3% 
Specifies whether the scroll bar arrows are enabled or disabled, and which ar- 
rows are enabled or disabled. This parameter can be one of the following values: 
Value == + ~—_—sC Meaning | : 
ESB_ENABLE_BOTH Enables both arrows of a scroll bar. 


ESB_DISABLE_LTUP | Disables the left arrow of a horizontal scroll bar, or the 
up arrow of a vertical scroll bar. 


Return Value 


Example 


See Also 


EnableWindow | 257 


Value Meaning 


-~ESB DISABLE RTDN Disables the right arrow of a horizontal scroll bar, or 
the down arrow of a vertical scroll bar. 
ESB DISABLE BOTH Disables both arrows of a scroll bar. 


The return value is nonzero if the arrows are enabled or disabled as specified. 


Otherwise, it is zero, indicating that the arrows are already in the requested state or 
that an error occurred. 


The following example enables an edit control’s vertical scroll bar when the con- 


trol receives the input focus, and disables the scroll bar when the control loses the 
focus: 


case EN_SETFOCUS: 


EnableScrolilBar(hwndMLEdit, SB_VERT, ESB _ENABLE_BOTH); 
break; | 


case EN _KILLFOCUS: 


EnableScrollBar(hwndMLEdit, SB_VERT, ESB _DISABLE_BOTH); 
break; 


ShowScrollBar 


EnableWindow 2x | 


BOOL EnableWindow(hwnd, fEnable) 


HWND hwnd; 
BOOL fEnable; 


Parameters 


Return Value 


/* handle of window #/ 
/* flag for enabling or disabling input */. 


The Enable Window function enables or disables mouse and keyboard input to the 
given window or control. When input is disabled, the window ignores input such 


as mouse clicks and key presses. When input is enabled, the window processes all 
input. 


hwnd 
Identifies the window to be enabled or disabled. 


fEnable 


Specifies whether to enable or disable the window. If this parameter is TRUE, 
the window is enabled. If the parameter is FALSE, the window is disabled. 


The return value is nonzero if the window was previously disabled. Otherwise, the 
return value is zero. 
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Comments If the enabled state of the window is changing, a WM_ENABLE message is sent 
before this function returns. If a window is already disabled, all its child windows 
are implicitly disabled, although they are not senta WM_ENABLE message. 


A window must be enabled before it can be activated. For example, if an applica- 
tion is displaying a modeless dialog box and has disabled its main window, the ap- 
plication must enable the main window before destroying the dialog box. 
Otherwise, another window will receive the input focus and be activated. If a child 
window is disabled, it is ignored when Windows tries to determine which window 
should receive mouse messages. 


By default, a window is enabled when it is created. An application can specify the 
WS_DISABLED style in the CreateWindow or CreateWindowEx function to 
create a window that is initially disabled. After a window has been created, an ap- 
plication can use the EnableWindow function to enable or disable the window. 


An application can use this function to enable or disable a control in a dialog box. 
A disabled control cannot receive the input focus, nor can a user access it. 


Example The following example enables a Save push button in a dialog box, depending on 
whether a user-specified filename exists: 


static char szFileName[128]; 
case WM_INITDIALOG: 
| /* If a filename is specified, enable the Save push button. */ 
EnableWindow(GetDlgItem(hdig, IDOK), 


(szFileName[@] == '\@" ? FALSE : TRUE)); 
return TRUE; 


See Also IsWindowEnabled 


EndDeferWindowPos | | | 


BOOL EndDeferWindowPos(idwp) _ 
HDWP hdwp; /* handle of internal structure we 


The EndDeferWindowPos function simultaneously updates the position and size 
of one or more windows in a single screen-refresh cycle. 
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Parameters hdwp 
a Identifies an internal structure that contains size and position information for 
one or more windows. This structure is returned by the BeginDefer Window- 

Pos function or by the most recent call to the Defer WindowPos function. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments | This function sends the WM_WINDOWPOSCHANGING and | | 
WM_WINDOWPOSCHANGED messages to each window identified in the inter- 
nal structure. 


See Also BeginDeferWindowPos, DeferWindowPos 


EndDialog arc 


void EndDialog(hwndDlg, nResult) 
HWND hwnabD le; /* handle of dialog box | 
int nResult; /* value to return */ 


The EndDialog function hides a modal dialog box and causes the DialogBox func- 
tion to return. ose 


Parameters hwndDlg 
| Identifies the dialog box to be destroyed. 


nResult | 
Specifies the value that is returned to the caller of DialogBox. 


Return Value ~ This function does not return a value. 


| Comments The EndDialog function is required to complete processing of a modal dialog box 
7 created by the DialogBox function. An ae n calls mel al08 from within | 
the dialog box procedure. | 


A dialog box procedure can call EndDialog at any fie: even during the pro- 
cessing of the WM_INITDIALOG message. If the function is called while 
WM_INITDIALOG is being processed, the dialog box 1 is hidden before itis — 
shown and before the input focus is set. _ 
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EndDialog does not destroy the dialog box immediately. Instead, it sets a flag that 
directs Windows to destroy the dialog box when the DialogBox function returns. 


See Also DialogBox 


EndDoc [3.1 | 


int EndDoc(hdc) | 
HDC hdc; /* handle of device context */ 


The EndDoc function ends a print job. This function replaces the ENDDOC 
printer escape for Windows version 3.1. 


Parameters — hdc 
Identifies the device context for the print job. 


Return Value The return value is greater than or equal to zero if the function is successful. Other- 
wise, it is less than zero. 


Comments An application should call the EndDoc function immediately after finishing a 
successful print job. To terminate a print job because of an error or if the user 
chooses to cancel the job, an application should call the AbortDoc function. 


Do not use the EndDoc function inside metafiles. 


See Also AbortDoc, Escape, StartDoc 


EndPage ee EXE 
int EndPage(hdc) | 
HDC hdc; _—s—/* handle of device context =] 


The EndPage function signals the device that the application has finished writing 
to a page. This function is typically used to direct the driver to advance to a new 


page. 


This function replaces the NEWFRAME printer escape for Windows 3.1. Unlike 
NEWFRAME, this function is always called after printing a page. | 
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Parameters hdc | 
Identifies the device context for the print job. 


Return Value The return value is greater than or equal to zero if the function is successtul. Other- 
wise, it 1S an error value. 


Errors If the function fails, it returns one of the following error values: 
Value Meaning 
SP_ERROR General error. a 
SP_APPABORT Job was terminated because the application’s print- 
: canceling function returned zero. 
~SP_USERABORT User terminated the job by using Windows Print Manager 
(PRINTMAN.EXE). 


SP_OUTOFDISK Not enough disk space is currently available for spooling, 
and no more space will become available. — | 


SP_OUTOFMEMORY. ___ Not enough memory is available for spooling. 


Comments The ResetDC function can be used to change the device mode, if necessary, after: 
calling the EndPage function. : 


See Also Escape, ResetDC, StartPage 


EndPaint Riles © tee Bae] 
void EndPaint(hwnd, Ipps) - 


HWND hwnd; /* handle of window a | 
const PAINTSTRUCT FAR®* Ipps; /* address of structure for paint data ay 


The EndPaint function marks the end of painting in the given window. This func- 
tion is required for each call to the BeginPaint function, but only after painting is 
~ complete. 


Parameters = = hwnd 
| Identifies the window that has been repainted. : 
[pps | 
~ Points toa PAINTSTRUCT structure that contains the painting information re- 
trieved by the BeginPaint function. The PAINTSTRUCT structure has the fol- 


- lowing form: 


262 EnumChildProc 


typedef struct tagPAINTSTRUCT { /* ps */ 
HDC hdc; : 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 

} PAINTSTRUCT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value - This function does not return a value. 


Comments If the caret was hidden by the BeginPaint function, the EndPaint function re- 
stores the caret to the screen. 


See Also BeginPaint 


EnumChildProc - Es 


BOOL CALLBACK EnumChildProc(hwnd, lParam) 
HWND hwnd; /* handle of child window */ 
~LPARAM /Param; /* application-defined value i 


The EnumChildProc function is an application-defined callback function that re- 
ceives child window handles as a result of a call to the EnumChild Windows func- 
tion. 


Parameters hwnd | | 

| Identifies a child window of the parent window specified in the Enum- 
Child Windows function. 

[Param 


Specifies the application-defined value specified in the EnumChild Windows 
function. 


Return Value The callback function must return nonzero to continue enumeration; to stop 
| enumeration, it must return zero. 


Comments The callback function can carry out any desired task. 


An application must register this callback function by passing its address to the 
EnumChild Windows function. The EnumChildProc function is a placeholder 
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for the application- defined function name. The actual name must be exported by 
including it in an EXPORTS siatement in the appucanion S mene definition 
(.DEF) file. 


See Also EnumChild Windows 


EnumChildWindows a 


BOOL EnumChild Windows(iwndParent, wndenmprc, lParam) 


HWND hwndParent; /* handle of parent window tf 
WNDENUMPROC i cael ie /* address of callback function = */ 
LPARAM lParam; /* application-defined value | **/ 


‘The EnumChild Windows function enumerates the child windows that belong to 
the given parent window by passing the handle of each child window, in turn, to 
an application-defined callback function. EnumChild Windows continues until 
the last child window is enumerated or the callback function returns zero. 


Parameters hwndParent 7 | 
Identifies the parent window whose child windows are to be enumerated. 


wndenmpre 3 
Specifies the proceduré- instance address of the application-supplied callback 
- function. The address must have been created by using the MakeProcInstance 
function. For more information about the callback function, see the description 
of the EnumChildProc callback function. | 


[Param 
_ Specifies a 32-bit application- defined value to pass to the callback function. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments This function does not enumerate top-level windows that belong to the parent win- 
dow. Oe 


If a child window has created child windows of its own, the function enumerates 
those windows as well. | 


_ Achild window that is moved or repositioned in the Z-order during the enumera- 
tion process will be properly enumerated. The function will not enumerate a child 
window that is destroyed before it is enumerated or that is created during the 
enumeration process. These measures ensure that the EnumChild Windows func- 
tion is reliable even when the application causes odd side effects, whereas an ape 
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cation that uses a Get Window loop risks being caught in an infinite loop or refer- 
encing a handle to a window that has been destroyed. 


See Also EnumChildProc, MakeProcInstance 


EnumClipboardFormats [2x] 


UINT EnumClipboardFormats(uFormat) 
UINT uFormat; /* known clipboard format i 


The EnumClipboardFormats function enumerates the formats found in a list of 
available formats that belong to the clipboard. Each call to this function specifies a 
known available format; the function returns the format that appears next in the 
list. 


Parameters uFormat 
Specifies a known format. If this parameter is zero, the function returns the first 
format in the list. 


Return Value The return value specifies the next known clipboard data format if the function is 
3 successful. It is zero if the uFormat parameter specifies the last format in the list 
of available formats, or if the clipboard is not open. 


Comments Before it enumerates the formats by using the EnumClipboardFormats function, 
an application must open the clipboard by using the OpenClipboard function. 


An application puts (or “donates’’) alternative formats for the same data into the 
clipboard in the same order that the enumerator uses when returning them to the 
pasting application. The pasting application should use the first format enumerated 
in the list that it can handle. This gives the donor application an opportunity to rec- 
ommend formats that involve the least loss of data. 


See Also CountClipboardFormats, GetClipboardFormatName, GetPriorityClipboard- 
Format, Pe eee eee ee OpenClipboard, RegisterClipboard- 
Format 
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EnumFontFamilies [3.1 | 


int EnumFontFamilies(hdc, lpszFamily, fntenmprc, l[Param) 


HDC hdc; /* handle of device context */ 

LPCSTR IpszFamily; /* address of font-family name **/ 

FONTENUMPROC fntenmprc; /* address of callback function sa 

LPARAM /Param; /* application-defined data **/ 
The EnumFontFamilies function enumerates the fonts in a specified font family 
that are available on a given device. EnumFontFamilies continues until there are 
no more fonts or the callback function returns zero. 

Parameters hdc 


Identifies the device context. 


lpszFamily 
Points to a null-terminated string that specifies the family name of the Acad 
fonts. If this parameter is NULL, the EnumFontFamilies function selects and 
enumerates one font from each available font family. 


fntenmpre 
Specifies the procedure-instance address of the application-defined callback 
function. The address must be created by the MakeProcInstance function. For 
more information about the callback function, see the description of the Enum- 
FontFamProc callback function. | 


- [Param 


Return Value 


Comments 


Example 


Specifies a 32-bit application- defined value that is passed to the callback func- 
tion along with the font information. | 


The return value specifies the last alle returned by the callback function, if the — 


- function is successful. This value depends on which font families are available for 


the given eyice 


The EnumFontFamilies function differs from the EnumFonts function in that it 
retrieves the style names associated with a TrueType font. Using EnumFont- | 
Families, an application can retrieve information about unusual font styles (for ex- 
ample, Outline) that cannot be enumerated by using the EnumFonts function. 


Applications should use EnumFontFamilies instead of EnumFonts. 


For each font having the font name specified by the /pszFamily parameter, the 
EnumFontFamilies function retrieves information about that font and passes it to 
the function pointed to by the fntenmprc parameter. The application-supplied call- _ 
back function can process the font information, as peccoeatye 


The following sable uses the MakeProcInstance function to create a pointer to 
the callback function for the EnumFontFamilies function. The FreeProcInstance 
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See Also 


function is called when enumeration is complete. Because the second parameter is 
NULL, EnumFontFamilies enumerates one font from each family that is availa- 
ble in the given device context. The aFontCount variable points to an array that is 
used inside the callback function. 


FONTENUMPROC 1pEnumFamCal1Back; 
int aFontCount[] = { 0, 0, @ }; 


lpEnumFamCallBack = (FONTENUMPROC) MakeProcInstance( 

(FARPROC) EnumFamCallBack, hAppInstance) ; 
EnumFontFamilies(hdc, NULL, ]pEnumFamCal1Back, (LPARAM) aFontCount); 
FreeProcInstance((FARPROC) 1pEnumFamCal1Back); 


EnumFonts, EnumFontFamProc 


EnumFontFamProc EN 


int CALLBACK EnumFontFamProc(/pnl/f, lpnim, FontType, l[Param) 


LOGFONT FAR® [pnif; /* address of structure with logical-font data | 
TEXTMETRIC FAR* [pntm; /* address of structure with physical-font data */ 
int FontType; /* type of font */ 
LPARAM /Param; /* address of application-defined data a 


Parameters 


The EnumFontFamProc function is an application-defined callback function that 
retrieves information about available fonts. 


Ipnlf : 


Points to a NEWLOGFONT structure that contains information about the logi- 
cal attributes of the font. This structure is locally-defined and is identical to the 
Windows LOGFONT structure except for two new members. The 
NEWLOGFONT structure has the following form: 


struct tagNEWLOGFONT { /* nif */ 
int  1fHeight; 
int 1fWidth; 
int l1fEscapement; 
int 1fOrientation; 
int lfWeight; 
BYTE IJfItalic; | 
BYTE 1fUnderline; 
BYTE 1fStrikeOut; 
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BYTE 1fCharSet; 

BYTE 1lfOutPrecision;. 

BYTE J1fClipPrecision; 

BYTE 1lfQuality; 

BYTE 1fPitchAndFamily; 

BYTE 1fFaceName[LF_FACESIZE]; 

BYTE 1lfFullName[2 * LF_FACESIZE]; /* TrueType only */ 

BYTE 1fStyleLLF_FACESIZE]; /* TrueType only */ 
} NEWLOGFONT; 


The IfFullName and IfStyle members are appended to a LOGFONT structure 
when a TrueType font is enumerated in the EnumFontFamProc function. 


The IfFullName member is a character array specifying the full name for the 
font. This name contains the font name and style name. 


The IfStyle member is a character array specifying the style name for the font. 


For example, when bold italic Arial® is enumerated, the last three members of 
the NEWLOGFONT structure contain the following strings: 


lfFaceName = “Arial”: 
IfFullName = “Arial Bold Italic’; 
lIfStyle = “Bold Italic”; 


For a full description of the LOGFONT structure, see the rca Windows 
Programmer’ s BES Volume 3. : 


Ipntm . 

Points toa NEWTEXTMETRIC structure that contains information about the 
physical attributes of the font, if the font is a TrueType font. If the font is not a 
TrueType font, this parameter points to a TEXTMETRIC structure. 


The NEWTEXTMETRIC structure has the following form: 


typedef struct tagNEWTEXTMETRIC { /* ntm */. 
int tmHeight; 
int tmAscent; 
int tmDescent; 
int tmInternalLeading; 
int tmExternalLeading; — 
int tmAveCharWidth; 
int tmMaxCharwWidth; 
int tmWeight; 
BYTE tmItalic; 
BYTE tmUnderlined; 
BYTE. tmStruckOut; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
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Return Value 


Comments 


See Also 


BYTE tmCharSet; 
int  tmOverhang; | 
int  tmDigitizedAspectx; 
int tmDigitizedAspecty; 
DWORD ntmFlags; 
UINT ntmSizeEM; 
UINT ntmCellHeight; 
UINT ntmAvgWidth; 
} NEWTEXTMETRIC; 


The TEXTMETRIC structure is identical to NEWTEXTMETRIC except 
that it does not include the last four members. For a full description of these 
structures, see the Microsoft Windows Programmer’s Reference, Volume 3. 


FontType 
Specifies the type of the font. This parameter can be a combination of the fol- 
- lowing masks: | 


DEVICE_FONTTYPE 
RASTER_FONTTYPE 
TRUETYPE_FONTTYPE 


lParam 
Points to the application-defined data passed by EnumFontFamilies. 


This function must return a nonzero value to continue enumeration; to stop 
enumeration, it must return zero. 


An application must register this callback function by passing its address to the 
EnumFontFamilies function. The EnumFontFamProc function is a placeholder 
for the application-defined function name. The actual name must be exported by 
including it in an EXPORTS statement in the application’s module-definition 
(.DEF) file. 


The AND (&) operator can be used with the RASTER_FONTTYPE, 
DEVICE_FONTTYPE, and TRUETYPE FONTTYPE constants to determine the 
font type. If the RASTER_FONTTYPE bit is set, the font is a raster font. If the 
TRUETYPE_FONTTYPE bit is set, the font is a TrueType font. If neither bit is 
set, the font is a vector font. A third mask, DEVICE_FONTTYPE, is set when a 
device (for example, a laser printer) supports downloading TrueType fonts; it is 
zero if the font is not a device font. (Any device can support device fonts, includ- 
ing display adapters and dot-matrix printers.) An application can also use the 
DEVICE_FONTTYPE mask to distinguish GDI-supplied raster fonts from device- 
supplied fonts. GDI can simulate bold, italic, underline, and strikeout attributes for 
GDI-supplied raster fonts, but not for device-supplied fonts. 


EnumFontFamilies, EnumFonts 


EnumFonts 
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ax] 


int EnumFonts(hdc, [pszFace, fntenmprc, lParam) 


HDC hdc; 
LPCSTR [pszFace; 


/* handle of device context */ 
/* address of font name **/ 


FONTENUMPROC fntenmprc; /* address of callback function sy 


LPARAM /Param; 


/* application-defined data i 


The EnumFonts function enumerates the fonts available for a given device. This 


_ function is provided for backwards compatibility with earlier versions of Win- 


Parameters 


Return Value 


Comments 


dows; current applications should use the EnumF ontFamilies function. 


EnumFonts continues until there are no more fonts or the callback function re- 
turns zero. 


hdc 
Identifies the device context. 


lpszF'ace 
Points to a null-terminated string that specifies the names of the requested 
fonts. If this parameter is NULL, the EnumFonts function randomly selects 
and enumerates one font from each available typeface. 


fntenmpre 
Specifies the procedure-instance address of the application- -defined callback 
function. The address must be created by the MakeProcInstance function. For 
more information about the callback function, see the description of the Enum- 
- FontsProc callback function. 


lParam 
Specifies a 32-bit application-defined value that is passed to the callback func- 
tion along with the on information. 


The return value specifies the last value returned by the callback function and is 
defined by the user. 


The EnumFonts function retrieves information about the specified font and 
passes it to the function pointed to by the fntenmprc parameter. The application- 
supplied callback function can process the font information, as necessary. 


If the device is capable of text transformations (scaling, italicizing, and so on), 

only the base font will be enumerated. The user must know the device’s text-trans- 
formation abilities to determine which additional fonts are available directly from 
the device. The graphics device interface (GDI) can simulate the bold, italic, uncer 
lined, and strikeout attributes for any GDI-based font. 


The EnumFonts function enumerates fonts from the GDI internal table only. 
This does not include fonts that are generated by a device, such as fonts that are 
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Example 


See Also 


EnumFontsProc 


transformations of fonts from the internal table. The GetDeviceCaps function can 
be used to determine which transformations a device can perform. This informa- 
tion is available by using the TEXTCAPS index. 


GDI can scale GDI-based raster fonts by one to five units horizontally and one to 
eight units vertically, unless PROOF_QUALITY is being used. 


The following example uses the MakeProcInstance function to create a pointer to 
the callback function for the EnumFonts function. The FreeProcInstance func- 
tion is called when enumeration is complete. Because the second parameter is 
“Arial”, EnumFonts enumerates the Arial fonts available in the given device con- 
text. The cArial variable is passed to the callback function. 


FONTENUMPROC 1lpEnumFontsCal1Back; 
int cArial = Q; 


]pEnumFontsCallBack = (FONTENUMPROC) MakeProcInstance( 
(FARPROC) EnumFontsCallBack, hAppInstance) ; 

EnumFonts(hdc, “Arial”, IpEnumFontsCallBack, (LPARAM) &cArial); 

FreeProcInstance((FARPROC) lpEnumFontsCal1Back); 


EnumFontFamilies, EnumFontsProc 


int CALLBACK EnumFontsProc(/p/f, [pnim, FontType, lpData) 


LOGFONT FAR® Ipi/f; /* address of logical-font data structure */ 
NEWTEXTMETRIC FAR® [pnim; /* address of physical-font data structure ig 
int FontType; /* type of font **/ 
LPARAM [pData; /* address of application-defined data i 


Parameters 


The EnumFontsProc function is an application-defined callback function that 
processes font data from the EnumFonts function. 


lplf 
Points to a LOGFONT structure that contains iafemnanon about the logical at- 
tributes. of the font. The LOGFONT structure has the mows form: 


typedef struct tagLOGFONT { je Lt * / 
int lfHeight;. 
int 1fWidth; 
int 1fEscapement; 
int JlfOrientation; 
int lfWeight; 
BYTE 1fiItalic; 
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BYTE 1lfUnderline; 

BYTE 1fStrikeOut; 

BYTE 1lfCharSet; 

BYTE 1fOutPrecision; 

BYTE 1fClipPrecision; 

BYTE IlfQuality; 

BYTE 1fPitchAndFamily; | 

BYTE 1lfFaceName[LF_FACESIZE]; 
} LOGFONT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


[pntm 
Points toa NEWTEXTMETRIC structure that contains information about the 
physical attributes of the font, if the font is a TrueType font. If the font is not a 
TrueType font, this parameter points to a TEXTMETRIC structure. 


The NEWTEXTMETRIC structure has the following form: 


typedef struct tagNEWTEXTMETRIC { /* ntm */ 
int  tmHeight; 
int tmAscent; 
int tmDescent; 
int tmInternal Leading; 
int tmExternalLeading; 
int tmAveCharWidth; 
int tmMaxCharWidth; 
int tmWei ght; 
BYTE tmItalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; 
int tmOverhang; 
int tmDigitizedAspectx; 
int tmDigitizedAspectyY; 
DWORD ntmFlags; 
UINT ntmSizeEM; 
UINT ntmCellHeight; 
UINT ntmAvgWidth; 
} NEWTEXTMETRIC; 


The TEXTMETRIC structure is identical to NEWTEXTMETRIC except 
that it does not include the last four members. For a full description of these 
_ Structures, see the Microsoft Windows Programmer’s Reference, Volume 3. 
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Return Value 


Comments 


FontType 
Specifies the type of the font. This parameter can be a combination of the fol- 
lowing masks: | 


DEVICE_FONTTYPE 
RASTER_FONTTYPE 
TRUETYPE_FONTTYPE 


lpData 
Points to the application-defined data passed by the EnumFonts function. 


This function must return a nonzero value to continue enumeration; to stop 
enumeration, it must return zero. 


An application must register this callback function by passing its address to the 
EnumFonts function. The EnumFontsProc function is a placeholder for the ap- 
plication-defined function name. The actual name must be exported by including it 
in an EXPORTS statement in the application’s module-definition (.DEF) file. 


The AND (&) operator can be used with the RASTER_FONTTYPE, 
DEVICE_FONTTYPE, and TRUETYPE_FONTTYPE constants to determine the 
font type. If the RASTER_FONTTYPE bit is set, the font is a raster font. If the 
TRUETYPE_FONTTYPE bit is set, the font is a TrueType font. If neither bit is. 
set, the font is a vector font. A third mask, DEVICE_FONTTYPE, is set when a 
device (for example, a laser printer) supports downloading TrueType fonts; it is 
zero if the device is a display adapter, dot-matrix printer, or other raster device. An 
application can also use the DEVICE_FONTTYPE mask to distinguish GDI- 
supplied raster fonts from device-supplied fonts. GDI can simulate bold, italic, 
underline, and strikeout attributes for GDI-supplied raster fonts, but not for device- 


_ supplied fonts. 


See Also 


EnumMetaFile 


EnumFonts, EnumFontFamilies 


BOOL EnumMetaFile(idc, hmf, mfenmprc, lParam) 


HDC hdc; 
HLOCAL hinf; 


/* handle of device context _ *f 
/* handle of metafile a aa | 


MFENUMPROC mfenmprc; -/* address of callback function *f. 


LPARAM /Param; 


/* application-defined data +) 


The EnumMetaFile function enumerates the metafile records in a given metafile. 
Enum MetaFile continues until there are no more graphics device interface (GDI) 
calls or the callback function returns zero. : 


Parameters 


Return Value 


Comments 


Example 
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hdc 
Identifies the device context associated with the metafile. 


hmf 
Identifies the metafile. 


Note The HLOCAL type for this parameter is incorrect in the WINDOWS.H 
file. The type of this parameter is actually HMETAFILE. Developers should 
cast this parameter to an HLOCAL type to avoid compiler warnings. 


mfenmprc 
Specifies the procedure-instance address of the application-supplied callback 
function. The address must be created by using the MakeProcInstance func- 
tion. For more information about the callback function, see the description of 
the EnumMetaFileProc callback function. 


[Param 
Specifies a 32-bit aeolian: -defined value that is passed to the callback func- 
tion along with the metafile information. 


The return value is nonzero if the callback function enumerates all the GDI calls i in 
a metafile. Otherwise, it is zero. 


The EnumMetaFile function retrieves metafile records and passes them to a call- — 
_back function. An application can modify the metafile record inside the callback 


function. The application can also use the PlayMetaFileRecord function inside 
the callback function; this is useful for very large metafiles, when using the Play- 
MetaFile function might be time-consuming. 


The following example creates a dashed green pen and passes it to the callback 
function for the EnumMetaFile function. If the first element in the array of object 
handles is a handle, that handle is replaced by the handle of the green pen before 


the PlayMetaFileRecord function is called. (For this example, it is assumed that 


the table of object handles contains only one handle and that it is the handle of a 
pen.) 


MFENUMPROC ee ee 
HPEN hpenGreen; 


]TpEnumMetaProc = (MFENUMPROC) MakeProcInstance( 

(FARPROC) EnumMetaFileProc, hAppInstance) ; 
hpenGreen = CreatePen(PS_DASH, 1, RGB(@, 255, 0)); 
EnumMetaFile(hdc, hmf, TpEnumMetaProc, (LPARAM) &hpenGreen) ; 
FreeProcInstance((FARPROC) IpEnumMetaProc) ; 
DeleteObject(hpenGreen) ; 
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int FAR PASCAL EnumMetaFileProc(HDC hdc, HANDLETABLE FAR* 1pHTable, 
METARECORD FAR* IpMFR, int cObj, BYTE FAR* 1IpClientData) 


{ 
if (lpHTable->objectHandle[Q] != @) 
lpHTable->objectHandle[@] = *(HPEN FAR *) IpClientData; 
PlayMetaFileRecord(hdc, IpHTable, IpMFR, cObj); 
return 1; 
} 
See Also EnumMetaFileProc, MakeProcInstance, PlayMetaFile, PlayMetaFileRecord 
EnumMetaFileProc [3.1 | 
int CALLBACK EnumMetaF ileProc(hdc, Ipht, Ipmr, cObj, [Param) 
HDC hdc; /* handle of device context */ 
HANDLETABLE FAR?® I[pht; /* address of table of object handles */ 
METARECORD FAR* Ipmr; /* address of metafile record sa 
int cObj; /* number of objects in handle table a 
LPARAM /Param; /* address of application-defined data */ 
The EnumMetaFileProc function is an application-defined callback function that 
processes metafile data from the EnumMetaFile function. 
Parameters hdc 
Identifies the special device context that contains the metafile. 
lpht | 


Return Value 


Comments 


Points to a table of handles associated with the objects (pens, brushes, and so 
on) in the metafile. 
Ipmr | 
Points to a metafile record eonanied in the metafile. 


cObj 
Specifies the number of objects with ceed handles in the handle table. 


[Param 
Points to the application-defined data. 


The callback function must return a nonzero value to continue enumeration; to 


stop enumeration, it must return zero. 


An application must register this callback function by passing its address to the 
Enum MetaFile function. 


See Also 
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The EnumMetaFileProc function is a placeholder for the application-defined 
function name. The actual name must be exported by including it in an 
EXPORTS statement in the application’s module-definition (.DEF) file. 


EnumMetaFile 


EnumObjects — : [2x | 


int EnumObjects(hdc, fnObjectType, goenmprc, lParam) 


HDC hdc; 
int fnObjectType; 


/* handle of device context | */ 
/* type of object */ 


GOBJENUMPROC goenmprc; /* address of callback function */ 


LPARAM /[Param; 


Parameters 


Return Value 


/* application-defined data a 


The EnumObjects function enumerates the pens and brushes available in the 
given device context. For each object of a given type, the callback function is 
called with the information for that object. EnumObjects continues until there are 
no more objects or the callback function returns zero. 


hdc “ 3 
Identifies the device context. 
jnObjectType 
Specifies the object type. This parameter can be one of the following values: 
Value Meaning | 
OBJ_BRUSH Specifies a brush. 
OBJ PEN Specifies a pen. 
goenmpre 


Specifies the procedure-instance address of the application-supplied callback 

- function. The address must be created by the MakeProcInstance function. For 
more information about the callback function, see the description of the 
EnumObjectsProc callback function. 


_ lParam 


Specifies a 32- bit appieation ¢ -defined value that is pet to the callback func- 
tion. 


T he return value specifies the last value returned by the callback function anid | iS - 
defined by the user. 
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_ Example The following example retrieves the number of horizontally hatched brushes and 
fills LOGBRUSH structures with information about each of them: 


dtdefine MAXBRUSHES 5@ 


GOBJENUMPROC 1pProcCallback; 
HGLOBAL hglbl; 
LPBYTE IpbCountBrush; 


lpProcCallback = (GOBJENUMPROC) MakeProcInstance( 
(FARPROC) Callback, hinst); 


hglbl = GlobalAlloc(GMEM FIXED, sizeof(LOGBRUSH) 
* MAXBRUSHES); 

TpbCountBrush = (LPBYTE) GlobalLock(hglb1); 

*I1pbCountBrush = Q; 

EnumObjects(hdc, OBJ_BRUSH, 1pProcCallback, 
(LPARAM) 1lpbCountBrush); 


FreeProcInstance((FARPROC) IpProcCallback); 


int FAR PASCAL Callback(LPLOGBRUSH IpLogBrush, LPBYTE pbData) 


{ 
/* 
* The pbData parameter contains the number of horizontally 
* hatched brushes; the IpDest parameter is set to follow the 
* byte reserved for pbData and the LOGBRUSH structures that 
* have been filled with brush information. | 
* / 
LPLOGBRUSH IpDest = 
(LPLOGBRUSH) (pbData + 1 + (*pbData * sizeof(LOGBRUSH) )); 
if (lpLogBrush->1bStyle == 
BS_HATCHED && /* if horiz hatch */ 
]}pLogBrush->1bHatch == HS_HORIZONTAL) { 
*I]pDest++ = *IlpLogBrush; /* fills structure with brush info */ 
(*pbData) ++; /* increments brush count * / 
if (*pbData >= MAXBRUSHES) 
return @; 
} | 
| return 1; 
7 
See Also EnumObjectsProc, FreeProcInstance, GlobalAlloc, GlobalLock, 


MakeProclInstance 
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EnumObjectsProc | [3.1 | 


int CALLBACK EnumObjectsProc(/pLogObject, [pData) 
void FAR* [pLogObject; /* address of object , ey 
LPARAM IpData; /* address of application-defined data sf 


The EnumObjectsProc function is an application-defined callback function that 
processes object data from the EnumObjects function. 


Parameters | lpLogObject 
7 Points to a LOGPEN or LOGBRUSH structure that contains information 
about the attributes of the object. 


The LOGPEN structure has the following form: 
typedef struct tagLOGPEN { /* lgpn */ 

UINT lopnStyle; 

POINT lopnWidth; 


COLORREF lopnColor; 
} LOGPEN; . 


The LOGBRUSH structure has the following form: 


typedef . struct tagLOGBRUSH a /* Tb */ 


UINT ~~ ~‘TbStyle;_ 
COLORREF 1bColor; 
int | TbHatch; 

} LOGBRUSH; 


For a full description a these structures, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


[pData 
Points to the gs rae denned data passed by the EnumObjects function. 


Return Value — This function must return a nonzero value to continue enumeration; to stop 
7 enumeration, it must return zero. 


Comments An application must register this callback function by passing its address to the 
7 EnumObjects function. The EnumObjectsProc function is a placeholder for the 
| application-supplied function name. The actual name must be exported by includ- 
ing itin an EXPORTS statement in the appucalon s module- definition (.DEF) © 
file. | 
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Example The following example retrieves the number of horizontally hatched brushes and 
fills LOGBRUSH structures with information about each of them: 


dekdefine MAXBRUSHES 5@ 


GOBJENUMPROC 1pProcCallback; 
HGLOBAL hglbl; 
LPBYTE lpbCountBrush; 


lpProcCallback = (GOBJENUMPROC) MakeProcInstance( 
(FARPROC) Callback, hinst); 


hglb1 = GlobalAlloc(GMEM_FIXED, sizeof(LOGBRUSH) 
* MAXBRUSHES) ; 

TpbCountBrush = (LPBYTE) GlobalLock(hglb1); 

*]pbCountBrush = Q; | 

EnumObjects(hdc, OBJ_BRUSH, 1pProcCallback, 
(LPARAM) lpbCountBrush); 


FreeProcInstance((FARPROC) 1pProcCallback); 


int FAR PASCAL Callback(LPLOGBRUSH lpLogBrush, LPBYTE pbData) 
{ 

/* : 
* The pbData parameter contains the number of horizontally 
hatched brushes; the IpDest parameter is set to follow the 
* byte reserved for pbData and the LOGBRUSH structures that 
have been filled with brush information. 


* 


% 


* / 


LPLOGBRUSH IpDest = 
(LPLOGBRUSH) (pbData + 1 + (*pbData * sizeof(LOGBRUSH) )); 


if (lpLogBrush->I1bStyle == 
BS_HATCHED && /* if horiz hatch */ 
lpLogBrush->]bHatch == HS_HORIZONTAL) { 
*]pDest++ = *lpLogBrush; /* fills structure with brush info */ 
(*pbData) +4; : /* increments brush count 2 / 
if (*pbData >= MAXBRUSHES) 
return Q; 


} 


return 1;_ 


} 


See Also EnumObjects, FreeProcInstance, GlobalAlloc, GlobalLock, 
MakeProclInstance 
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EnumPropFixedProc | [2x | 


BOOL CALLBACK EnumPropFixedProc(hwnd, Ipsz, hData) 


HWND hwnd; /* handle of window with property i} 
LPCSTR Ipsz; /* address of property string or atom | 
HANDLE hData; /* handle data of property data +] 


The EnumPropFixedProc function is an application-defined callback function 
that receives a window’s property data as a result of a call to the EnumProps func- 
tion. : 


Parameters hwnd 

Identifies the handle of the window that contains the oper) list. 

[psz 
Points to the null-terminated string associated with the property data identified 

_ by the Data parameter. The application specified the string and data in a pre- _ 

- vious call to the SetProp function. If the application passed an atom instead of 

a string to SetProp, the /psz parameter contains the atom in the low-order word 
and zero in the pee word. 


hData 
nantes the property data. 


~ Return Value The callback Aietion must return TRUE to continue enumeration: it must return 
| FALSE to stop enumeration. | 


Comments This form of the ee -enumeration callback function should be used in applica- 
Oe ao ~ tions and dynamic-link libraries with fixed data segments and in dynamic libraries 
with movable data segments that do not contain a stack. 


The following restrictions apply t to the callback Gift on: 
= The callback function must not yield control or do anything that might yield 
control to other tasks. | 


= The callback function can call the RemoveProp function. However, Remove- 
Prop can remove only the property passed to the callback function through the — 
callback function’s parameters. 


= The callback function should not attempt to add per 

The EnumPropFixedProc function is a placeholder for the application-defined 
_ function name. The actual name must be exported by including it in an | 
_ EXPORTS statement in the application’s module-definition (.DEF) file. 


SeeAlso 8 EnumPropMovableProc, EnumProps, RemoveProp, SetProp 
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EnumPropMovableProc 


BOOL CALLBACK EnumPropMovableProc(hwnd, lpsz, hData) 


HWND hwnd; 
LPCSTR Ipsz; 
HANDLE hData; 


Parameters 


Return Value 


Comments 


/* handle of window with property sy 
/* address of property string or atom **/ 
/* handle of property data a 


The EnumPropMovableProc function is an application-defined callback function 
that receives a window’s property data as a result of a call to the EnumProps func- 
tion. 


hwnd 
Identifies the handle of the window that contains the property list. 


Ilpsz | 
Points to the null-terminated string associated with the data identified by the 
hData parameter. The application specified the string and data in a previous 
call to the SetProp function. If the application passed an atom instead of a 
String to SetProp, the /psz parameter contains the atom. 


hData 
Identifies the property data. 


The callback function must return TRUE to continue enumeration; to stop 
enumeration, it must return FALSE. 


This form of the property-enumeration callback function should be used in applica- 
tions with movable data segments and in dynamic libraries whose movable data 
segments also contain a stack. This form is required since movement of the data 
will invalidate any long pointer to a variable on the stack, such as the lpsz parame- 
ter. The data segment typically moves if the callback function allocates more 

space in the local heap than is currently available. 


The following restrictions apply to the callback function: 


= The callback function must not yield control or do anything that might yield 
control to other tasks. 


= The callback function can call the RemoveProp function. However, Remove- 
Prop can remove only the property passed to the callback function through the 
callback function’s parameters. 


“= The callback function should not attempt to add properties. 


The EnumPropMovableProc function is a placeholder for the application- 
defined function name. The actual name must be exported by including it in an 


_ EXPORTS statement in the application’s module-definition (.DEF) file. 
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See Also EnumPropFixedProc, EnumProps, RemoveProp, SetProp 


EnumProps 2x | 


int EnumProps(hwnd, prpenmprc) ae 
HWND hwnd; /* handle of window 5 | 
PROPENUMPROC prpenmprc; /* address of callback function tf 


The EnumProps function enumerates all entries in the property list of the given 
window. It enumerates the entries by passing them, one by one, to the specified 
callback function. EnumProps continues until the last pi is enumerated or the 
callback function returns zero. , 


_ Parameters hwnd | 
Identifies the window whose property list is enuihenited: 


prpenmprc 
Specifies the ere instance address of the ealiback function. For more in- 
formation, see the descriptions of the EnumPropFixedProc and EnumProp- 
MovableProc callback functions. os | 


Return Value The return value specifies the last value otarned by the callback function. It is — | 
| if the function did not find a property to enumerate. _ ) | 


Comments The form of the callback function oe on whether the application or dynamic- 
ee link library (DLL) uses fixed or movable data segments. If the application or 
library uses fixed data segments (or if the library uses movable data segments that 
do not contain a stack), see the description of the EnumPropFixedProc callback 
function. If the application uses movable data segments (or if the library uses mov- 
able data segments that also contain a stack), see the description of the Enum- — 
PropMovableProc callback function. 


An application’s EnumPropFixedProc or EnumPropMovableProc callback 
function should not add new properties to a window. If the callback function de- _ 
letes a window’s properties, it should delete only the property currently being 
enumerated. The callback function should not delete other properties belonging to... 
the window; if it does, the enumeration process terminates early. 


The address passed in the prpenmprc parameter must be created byt using the 
MakeProclInstance function. 


See Also EnumPropFixedProc, EnumPropMovableProe, GetProp, MakeProcInstance, 
ee SetProp 
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EnumTaskWindows 


BOOL EnumTask Windows(htask, wndenmprc, lParam) 


HTASK htask; 


/* handle of task | */ 


WNDENUMPROC wndenmprc; /* address of callback function */ 


LPARAM /Param; 


Parameters 


Return Value 


Comments 


See Also 


/* application-defined value | 


The EnumTask Windows function enumerates all windows associated with a 
given task. (A task is any program that executes as an independent unit. All appli- 
cations are executed as tasks, and each instance of an application is a task.) The 
function enumerates the windows by passing their handles, one by one, to the 
specified callback function. EnumTask Windows continues until the last entry is 
enumerated or the callback function returns zero. 


htask 
Identifies the task. The task handle must be retrieved by a previous call to the 
GetCurrentTask function. 


wndenmprc 
Specifies the procedure-instance address of the callback function. For more in- 
formation, see the description of the EnumTaskWndProc callback function. 


lParam | 
Specifies a 32-bit application-defined value that is passed to the callback func- 
tion along with each window handle. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


This function enumerates all top-level windows but does not enumerate child win- 
dows. 


The EnumTask Windows function is reliable even when the application causes 
odd side effects, whereas an application that uses a Get Window loop risks being 
caught in an infinite loop or referencing a handle to a window that has been de- 
stroyed. 


The address passed in the wndenmprc parameter must be created ou using the 
MakeProcInstance function. 


EnumTaskWndProc, GetCurrentTask 
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EnumTaskWndProc [2x | 


BOOL CALLBACK EnumTaskWndProc(hwnd, clare 
HWND hwnd; /* handle of a window 
LPARAM [Param; /* application-defined value " 


The EnumTaskWndProc function is an application-defined callback function 
that receives the window handles associated with a task as a result of a call to the 
EnumTask Windows function. | 


Parameters hwnd 
Identifies a window associated with the task specified in the EnumTask- 


Windows function. 

lParam 
Specifies the application-defined value specified in the EnumTask Windows 
function. 


Return Value The callback function must return TRUE to continue enumeration; to stop 
| enumeration, it must return FALSE. 


Comments The callback function can carry out any desired task. 


The EnumTaskWndProc function is a placeholder for the application-defined 
function name. The actual name must be exported by including it in an 
EXPORTS statement in the application’s module-definition (.DEF) file. 


See Also EnumTask Windows 


EnumWindows [2x] 


BOOL EnumWindows(wndenmprc, lParam) . 
WNDENUMPROC wndenmprc; /* address of callback function */ 
LPARAM /Param; /* application-defined value. “eh 


The Enum Windows function enumerates all parent windows on the screen by 

passing the handle of each window, in turn, to an application-defined callback 
function. Enum Windows continues until the last parent window is enumerated or 
the callback function returns zero. | 
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Parameters _ wndenmprc 
Specifies the procedure-instance address of the callback function. For more in- 
formation, see the description of the Enum WindowsProc callback function. 


lParam 
Specifies a 32-bit application-defined value that is passed to the callback func- 
tion. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The Enum Windows function does not enumerate child windows. 


Enum Windows is reliable even when the application causes odd side effects, 
whereas an application that uses a GetWindow loop risks being caught in an in- 
finite loop or referencing a handle to a window that has been destroyed. 


The address passed as the wndenmprc parameter must be created by using the 
MakeProcinstance function. 


See Also Enum WindowsProc, MakeProcInstance 


EnumWindowsProc ae e 


BOOL CALLBACK EnumWindowsProc(hwnd, lParam) 
HWND hwnd; /* handle of parent window */ 
LPARAM /Param; /* application-defined value i | 


The Enum WindowsProc function is an application-defined callback function that 
receives parent window handles as a result of a call to the Enum Windows func- 
tion. 


Parameters hwnd 
Identifies a parent window. 


[Param 
Specifies the application-defined value specified 1 in the Enum Windows func- — 
tion. | 


Return Value The callback function must return nonzero to continue enumeration; to stop 
enumeration, it must return zero. : 3 


Comments The callback function can carry out any desired task. 
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The EnumWindowsProc function is a placeholder for the application-defined 
function name. The actual name must be exported by including it in an 
EXPORTS statement in the application’s module-definition (.DEF) file. 


See Also Enum Windows 


EqualRect [2x | 


BOOL EqualRect(lprc/, [prc2) 
const RECT FAR® [prc/; /* address of structure with first rectangle **/ 


const RECT FAR® lprc2; /* address of structure with second rectangle */ 


The EqualRect function determines whether the two given rectangles are equal by 
comparing the coordinates of their upper-left and lower-right corners. 


Parameters lprcl 
Points to a RECT structure that contains the logical coordinates of the first 


rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


lprc2 
Points to a RECT structure that contains the logical coordinates of the second 


rectangle. 


Return Value The return value is nonzero if the two rectangles are identical. Otherwise, it is zero. 
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EqualRgn 


BOOL EqualRegn(hrgnSrcl, hrgnSrc2) 


HRGN hrgnSrc1; 


HRGN hregnSrc2; 


Parameters | 


Return Value 


Example 


i handle of first region to test for equality a 
/* handle of second region to test for equality | 


The EqualRgn function determines whether two given regions are identical. 


hrgenSrcl 
Identifies the first region. 


hrgnSrc2 
Identifies the second region. 


The return value is nonzero if the two regions are equal. Otherwise, it is zero. 


The following example uses the EqualRgn function to test the equality of a region 


against two other regions. In this case, hrgn?2 is identical to hrgn1, but hrgn3 is not 
identical to hrgn1. 


BOOL fEqual; | 

HRGN hrgnl, hrgn2, hrgn3; 

LPSTR lpszEqual = "Regions are equal."; 

LPSTR IpszNotEqual = "Regions are not equal."; 


hrgnl = CreateRectRgn(10, 10, 110, 110); /* 1 and 2 identical */ 
hrgn2 = CreateRectRgn(10, 10, 110, 110); © 
hrgn3 = CreateRectRgn(100, 100, 210, 210); /* same dimensions */ 


fEqual = EqualRgn(hrgnl, hrgn2); 

if (fEqual) 2 a 
TextOut(hdc, 10, 10, IpszEqual, Jstrlen(1lpszEqual)); 

else , | 
TextOut(hdc, 10, 10, IpszNotEqual, Istrlen(lpszNotEqual)); 


fEqual = EqualRgn(hrgnl, hrgn3); 


if (fEqual) 


TextOut(hdc, 10, 30, IpszEqual, Istrlen(lpszEqual)); 
else | 
— TextOut(hdc, 10, 30, IpszNotEqual, Istrien(1pszNotEqual)); 


DeleteObject(hrgnl); 
DeleteObject(hrgn2); 
DeleteObject(hrgn3); 


Escape 
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[ 2.x | 


int Escape(hdc, nEscape, cbInput, [pszInData, IpvOutData) 


HDC hdc; /* handle of device context s/f 

int nEscape; /* specifies escape function i 

int cbInput; /* size of structure for input ss 

LPCSTR IpszInData; /* address of structure for input */ 

void FAR* /pvOutData; /* address of structure for output a | 
The Escape function allows applications to access capabilities of a particular 
device that are not directly available through the graphics device interface (GDI). 
Escape calls made by an application are translated and sent to the driver. 

Parameters hdc 


Return Value 


‘Errors 


Identifies the device context. | 

nEscape | 
Specifies the escape function to be performed. For a complete list of printer 
escapes, see the Microsoft Windows Programmer’s Reference, Volume 3. 


cbInput | 
Specifies the number of bytes of data pointed to by the /psz/nData parameter. 


[pszInData 
Points to the input structure required for the specified escape. 


lpvOutData 
Points to the structure that receives output from this escape. This parameter 
should be NULL if no data is returned. 


The return value specifies the outcome of the function. It is greater than zero if the 
function is successful, except for the QUER YESCSUPPORT printer escape, 
which checks for implementation only. The return value is zero if the escape is not 
implemented. A return value less than zero indicates an error. 7 


If the function fails, the return value is one of the following: 


Value Meaning 
SP_ERROR General error. 
SP_OUTOFDISK Not enough disk space is currently available for spooling, 


and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through Print Manager. 
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LONG EscapeCommFunction(idComDev, nFunction) — 
int idComDev; /* identifies communications device * 
int nFunction; /* code of extended function */ 


The EscapeCommFunction function directs the specified communications device 
to carry out an extended function. 


Parameters idComDev 
Specifies the communications device that will carry out the extended function. 
The OpenComm function returns this value. 7 


nF unction 
Specifies the function code of the extended function. It can be one of the follow- 
ing values: 
Value Meaning 
CLRDTR Clears the DTR (data-terminal-ready) signal. 
CLRRTS Clears the RTS (request-to-send) signal. 


GETMAXCOM Returns the maximum COM port identifier supported by the 
system. This value ranges from 0x00 to 0x7F, such that 0x00 
corresponds to COM1, 0x01 to COM2, 0x02 to COM3, and so 
on. 

GETMAXLPT Returns the maximum LPT port identifier supported by the sys- 

tem. This value ranges from 0x80 to OxFF, such that 0x80 corre- 
sponds to LPT1, 0x81 to LPT2, 0x82 to LPT3, and so on. 


RESETDEV Resets the printer device if the idComDev parameter specifies 
| an LPT port. No function is performed if idComDev specifies a 

COM port. 

SETDTR | Sends the DTR (data-terminal-ready) signal. 

SETRTS Sends the RTS (request-to-send) signal. 

SETXOFF Causes transmission to act as if an XOFF character has been re- 
ceived. 

SETXON | | Causes transmission to act as if an XON character has been re- 
ceived. 


Return Value — The return value is zero if the function is successful. Otherwise, it is less than Zero. 
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ExcludeClipRect [2x | 


int ExcludeClipRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect) 


HDC hdc; 

int nLeftRect; 
int nTopRect; 
int nRightRect; 
int nBottomRect; 


Parameters 


Return Value 


Comments 


Example 


/* handle of device context a 
/* x-coordinate top-left corner of rectangle **/ 
/* y-coordinate top-left corner of rectangle a: 
/* x-coordinate bottom-right corner of rectangle **/ 
/* y-coordinate bottom-right corner of rectangle */ 


The ExcludeClipRect function creates a new clipping region that consists of the - 
existing clipping region minus the specified rectangle. 


hdc 
Identifies the device context. 


nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the rectangle. 


nTopRect | 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the rectangle. 


nBottomRect | : 
Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


The return value is SIMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR (no 
region is created). | 


The width of the rectangle, specified by the absolute value of nRightRect — 
nLeftRect, must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. 7 | 


The following example uses the ExcludeClipRect function to create a clipping re- 
gion in the shape of a frame that is 20 units wide. The frame is painted red when 
the FillRect function is used to paint the client area. 


RECT rc; 
HRGN hrgn; 
HBRUSH hbrRed; 


GetClientRect(hwnd, &rc); | 
hrgn = CreateRectRgn(10, 10, 110, 110); 
SelectClipRgn(hdc, hrgn); 


ExcludeClipRect(hdc, 30, 30, 90, 90); 
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hbrRed = CreateSolidBrush(RGB(255, 0, @)); 
FillRect(hdc, &rc, hbrRed); 


DeleteObject(hbrRed) ; 
DeleteObject(hrgn); 


See Also CombineRgn 


ExcludeUpdateRgn [2x] 


int ExcludeUpdateRgen(hdc, hwnd) 
HDC hdc; /* handle of device context */ 
HWND hwnd; /* handle of window */ 


The ExcludeUpdateRgn function prevents drawing within invalid areas of a win- 
dow by excluding an updated region in the window from a clipping region. 


Parameters hdc 
| Identifies the device context associated with the clipping region. 


hwnd 
Identifies the window to be updated. 


Return Value — The return value is SIMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR (no 
region is created). 


See Also BeginPaint, GetUpdateRect, GetUpdateRgn, UpdateWindow 


ExitWindows 


BOOL Exit Windows(dwReturnCode, reserved) 
DWORD dwReturnCode; /* return or restart code */ 
UINT reserved; __ /*® reserved; must be zero ae: 


The ExitWindows function can restart Windows, terminate Windows and return 
control to MS-DOS, or terminate Windows and restart the system. Windows sends 
the WM_QUERYENDSESSION message to notify all applications that a request 
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has been made to restart or terminate Windows. If all applications “agree” to termi- 
nate, Windows sends the WM_ENDSESSION message to all applications before 
terminating. 


Parameters dwReturnCode 
Specifies whether Windows should restart, terminate and return control to 
MS-DOS, or terminate and restart the system. The high-order word of this pa- 
rameter should be zero. The low-order word specifies the return value to be 
passed to MS-DOS when Windows terminates. The low-order word can be one 
of the following values: 


Value Meaning | | 
EW_REBOOTSYSTEM Causes Windows to terminate and the system to re- 
| Start. 


EW_RESTARTWINDOWS Causes Windows to restart. 


reserved 
Reserved; must be zero. 


Return Value The return vane is zero if one or more applications refuse to terminate. The func- 
tion does not return a value if all applications agree to be terminated. 


See Also | Exit WindowsExec 


ExitWindowsExeo 


BOOL ExitWindowsExec(/pszExe, lpszParams) 


LPCSTR IpszExe; 
LPCSTR IpszParams; 
The ExitWindowsExec function terminates Windows, runs a specified MS- DOs 
| application, and then restarts Windows. 
Parameters | lpszExe 


Points to a null-terminated string specifying the path and filename of thee execu- 
table file for the system to run after Windows has been terminated. This string _ 
must not be longer than 128 bytes Gacluding the null terminating character). 


IpszParams 

Points to a null-terminated string specifyilig a any parameters for the Eccuable - 

_ file specified by the IpszExe parameter. This string must not be longer than 127 
bytes (including the null terminating character). This value can be NULL. 
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Return Value | The return value is FALSE if the function fails. (The function could fail because 
of a memory-allocation error or if one of the applications i in the system does not 
terminate.) 

Comments The ExitWindowsExec function is typically used by installation programs to re- 


place components of Windows which are active when Windows is running. 


See Also ExitWindows 


ExtDeviceMode | 


#include <print.h> 


int ExtDeviceMode(hwnd, hDriver, lpdmOutput, lpszDevice, lpszPort, lpdmInput, ipszProfi le, fwMode) 
*/ 


HWND hwnd; /* handle of window 

HANDLE hDriver; /* handle of driver */ 
LPDEVMODE I[pdmOutput; /* address of structure for driver output sa 
LPSTR IpszDevice;  __ /* string for name of device | 
LPSTR [pszPort; /* string for name of port | ic 
LPDEVMODE [pdminput; /* address of structure for driver input wf 
LPSTR [pszProfile; /* string for profile filename | **/ 
WORD /fwMode; /* operations mask sf 


The ExtDeviceMode function retrieves or modifies device initialization informa- 
tion for a given printer driver or displays a driver-supplied dialog box for configur- 
ing the printer driver. Printer drivers that support device initialization by 
applications export ExtDeviceMode so that applications can call it. 


Parameters hwnd 
Identifies a window. If the application calls the ExtDeviceMode function to dis- 
play a dialog box, the specified window is the parent window of the dialog box. 


hDriver 
Identifies the device-driver module. The GetModuleHandle function or Load- 
Library function returns a module handle. | 


[pdmOutput 
Points to a DEVMODE structure. The driver writes the initialization informa- 
tion supplied in the [pdmInput parameter to this structure. The DEVMODE 
structure has the following form: 
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#include <print.h> 


typedef struct tagDEVMODE { /* dm */- 
char dmDeviceName[CCHDEVICENAME ]; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDriverExtra; 
DWORD dmFields; _ 
int dmOrientation; 
int dmPaperSize; 
int dmPaperLength; 
int dmPaperWidth; 
int dmScale; 
int dmCopies; 
int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; 
int  dmDuplex; 
int dmYResolution; 
int dmTTOption; 
} DEVMODE; 


For a full description of this structure, see the Microsoft Windows Program- 
_mer’s Reference, Volume 3. 3 


| IpsDevice | | 7 
Points to a null- terminated string that contains the name of the printer device— 
for example, PCL/HP LaserJet. | 


ipszPort 
Points to a null-terminated string that contains the name of the port to which the 
device is connected—for example, LPTl. aon 


ipdminput 
Points to a DEVMODE structure that supplies initialization information to the 
printer driver. 


lpszP rofile 
Points to a null-terminated string that contains the name of the initialization file, 
where initialization information is recorded and read from. If this parameter 1S 
NULL, WIN.INI is the default initialization file. 3 


JwMode 
Specifies a mask of values that detérinines the operations the function per- | 
forms. If this parameter is zero, the ExtDeviceMode function returns the num- 
ber of bytes required by the printer driver’s DEVMODE structure. Otherwise, 
the fwMode parameter can be one or more of the following values (to change 
the print settings, the application must specify at least one input value and one 
output value): 7 | 
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Return Value 


Comments 


Value Meaning 


DM_IN_BUFFER Input value. Before prompting, copying, or updating, 
| this value merges the printer driver’s current print set- 
tings with the settings in the DEVMODE structure iden- 
tified by the JpdmInput parameter. The structure is 
updated only for those members indicated by the applica- 
tion in the dmFields member. This value is also defined 
| as DM_MODIFY. 

DM_IN_PROMPT Input value. This value presents the printer driver’s Print 
Setup dialog box and then changes the settings in the 
printer’s DEVMODE structure to values specified by 
the user. This value is also defined as DM_PROMPT. 

DM_OUT_BUFFER Output value. This value writes the printer driver’s cur- 
rent print settings (including private data) to the DEV- 
MODE structure identified by the IpdmOutput 
parameter. The calling application must allocate a buffer 
sufficiently large to contain the information. If this bit is 
clear, JpdmOutput can be NULL. This value is also de- 
fined as DM_COPY. 

DM_OUT_DEFAULT Output value. This value updates graphics device inter- 
face (GDIJ)’s current printer environment and the 
WIN.INI file, using the contents of the printer driver’s 
DEVMODE structure. Avoid using this value, because it 
permanently changes the print settings for all applica- 
tions. This value is also defined as DM_UPDATE. 


If the fwMode parameter is zero, the return value is the size of the buffer required 
to contain the printer driver initialization data. (Note that this buffer can be larger 
than a DEVMODE structure, if the printer driver appends private data to the struc- 
ture.) If the function displays the initialization dialog box, the return value is either 
IDOK or IDCANCEL, depending on which button the user selects. If the function 
does not display the dialog box and is successful, the return value is IDOK. The re- 
turn value is less than zero if the function fails. 


The ExtDeviceMode function is part of the printer’s device driver and not part of 
GDI. To use this function, an application must retrieve the address of the function 
by calling the LoadLibrary and GetProcAddress functions, and it must include 
the header file PRINT.H. The application can then use the address to set up the 
printer. 


ExtDeviceMode is not supported by all printer drivers. If the GetProcAddress 
function returns NULL, ExtDeviceMode is not supported. 


To make changes to print settings that are local to the application, an application 
should call the ExtDeviceMode function, specifying the DM_OUT_BUFFER 
value; modify the returned DEVMODE structure; and then pass the modified 
DEVMODE structure back to ExtDeviceMode, specifying DM_IN_BUFFER 


See Also 


ExtFloodFill 
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and DM_OUT_BUFFER (combined by using the OR operator). The DEVMODE 
structure returned by this second call to ExtDeviceMode can be used as an argu- 
ment in a call to the CreateDC function. 


Any call to ExtDeviceMode must set either DM_ OUT_ BUFFER or 
DM_OUT_DEFAULT. 


An application can set the fwMode parameter to DM_OUT_BUFFER to obtain a 
DEVMODE structure filled with the printer driver’s initialization data. The appli- 
cation can then pass this structure to the CreateDC function to set a private en- 
vironment for the printer device context. | 


CreateDC, DeviceMode, GetModuleHandle, GetProcAddress, LoadLibrary 


BOOL ExtFloodFill(idc, nXStart, nYStart, clrref, fuFillType) 


HDC hdc; | 

int nXStart; 

— int nYStart; 
COLORREFE cirref; 
UINT fuFillType; 


/* handle of device context 


/* x-coordinate where filling begins | 
/* y-coordinate where filling begins aH 
/* color of fill 7] 
/* fill type | */ 


The ExtFloodFill function fills an area of the screen surface by using the current 


~ brush. The type of flood fill specified determines which part of the screen is filled. _ 


| Parameters 


hdc 
Identifies the device context. 


nX Start 
Specifies the logical x-coordinate at which to begin tilling. 


— nYStart 


Specifies the logical y-coordinate at which to begin filling. 
clrref 
Specifies the color of the boundary or area to be filled. The interpretation of this 
_ parameter depends on the value of the fuF ill Type pam | 
fuFillType : 
Specifies the ‘ype of flood fill to be eed. It must be one -af the following 
values: | | 
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Return Value 


Comments 


See Also 


Extracticon 


Value Meaning 


FLOODFILLBORDER Fill area is bounded by the color specified by the clrref 
parameter. This style is identical to the filling per- 
formed by the FloodFill function. 

~ FLOODFILLSURFACE Fill area is defined by the color specified by the clrref 
parameter. Filling continues outward in all directions 
as long as the color is encountered. This style is useful 
for filling areas that have multicolored boundaries. 


The return value is nonzero if the function is successful. It is zero if the filling can- 
not be completed, if the given point has the boundary color specified by the clrref 
parameter (if FLOODFILLBORDER was requested), if the given point does not 
have the color specified by clrref (if FLOODFILLSURFACE was requested), or if 
the point is outside the clipping region. 


Only memory device contexts and devices that support raster-display technology 
support the ExtFloodFill function. For more information about raster capabilities, 
see the description of the GetDeviceCaps function. 


If the fuFillType parameter is the FLOODFILLBORDER value, the area is as- 
sumed to be completely bounded by the color specified by the clrref parameter. 
The ExtFloodFill function begins at the coordinates specified by the nXStart and 
nYStart parameters and fills in all directions to the color boundary. 


If fuFillType is FLOODFILLSURFACE, ExtFloodFill begins at the coordinates 
specified by nXStart and nYStart and continues in all directions, filling all adjacent 
areas containing the color specified by clrref. 


FloodFill, GetDeviceCaps 


#include <shellapi.h> 


-HICON ExtractIcon(hinst, lpszExeName, ilcon) 


HINSTANCE hinst; 


/* instance handle */ 


LPCSTR IpszExeName; /* address of string forfile § */ 


UINT ilcon; 


/* index of icon to retrieve ed | 


The ExtractIcon function retrieves the handle of an icon from a specified execu- 
table file, dynamic-link library (DLL), or icon file. 


Parameters 


Return Value 


ExtTextOut 
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hinst | 
Identifies the instance of the applicalion calling the function. 


lpszExeName 
Points to a null-terminated string specifying the name of an executable file, 
dynamic-link library, or icon file. 


icon 
Specifies the index of the icon to be retrieved. If this parameter is zero, the — 
function returns the handle of the first icon in the specified file. If the parame- 
ter is —1, the function returns the total number of icons in the specified file. 


The return value is the handle of an icon if the function is successful. It is 1 if the 
file specified in the /pszExeName parameter is not an executable file, dynamic-link 
library, or icon file. Otherwise, it is NULL, indicating that the file contains no 
icons. . 


BOOL ExtTextOut(hdc, nXStart, nYStart, fuOptions, lprc, ips2String; cbString, lpDx) 
yi) 


HDC hdc; /* handle of device context 
int nXStart; /* x-coordinate of starting position i | 
int nYStart; /* y-coordinate of starting position oF 
UINT fuOptions; /* rectangle type el 
const RECT FAR®* [prc; /* address of structure with rectangle | f 
LPCSTR IpszString; /* address of string on) 
UINT cbString; /* number of bytes in string | =] 
int FAR* /pDx; /* spacing between character cells | eet] 
~The ExtTextOut function writes a character string within a rectangular region, 
using the currently selected font. The rectangular region can be opaque (filled by 
using the current background color as set by the SetBkColor function), and it ¢ can 
| be a clipping region. 
Parameters hdc 


Identifies the device context. 


~ nXStart 


Specifies the logical X- -coordinate at which the string begins. 


— -nYStart 


- Specifies the logical y-coordinate at which the string begins. 


_ fuOptions 


Specifies the reclanigle type. This parameter ¢ can ne one, both, or neither of the 
following values: | : 
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Value Meaning 


ETO_CLIPPED Text is clipped to the rectangle. 


ETO_OPAQUE Current background color fills the rectangle. (An application 
can set and query the current background color by using the 
SetBkColor and GetBkColor functions.) 


lpre 
Points to a RECT structure that determines the dimensions of the rectangle. 
The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; . 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


lpszString 
Points to the specified character string. 


cbString 
Specifies the number of bytes in the string. 


lpDx 
Points to an array of values that indicate the distance, in logical units, between 
origins of adjacent character cells. The nth element in the array specifies the 
number of logical units that separate the origin of the nth item in the string from 
the origin of item 7 + 1. If this parameter is NULL, ExtTextOut uses the de- 
fault spacing between characters. Otherwise, the array contains the number of 
elements specified in the cbString parameter. 


Return Value — The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments _ If the fuOptions parameter is zero and the Jprc parameter is NULL, the Ext- 
_ TextOut function writes text to the device context without using a rectangular re- 
gion. | 


By default, the current position is not used or updated by ExtTextOut. If an appli- 
cation needs to update the current position when it calls ExtTextOut, the applica- 
tion can call the SetTextAlign function with the wFlags parameter set to 
TA_UPDATECP. When this flag is set, Windows ignores the nXStart and nYStart 
parameters on subsequent calls to ExtTextOut, using the current position instead. 
When an application uses TA_UPDATECP to update the current position, Ext- 
TextOut sets the current position either to the end of the previous line of text or to 
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the position specified by the last element of the array pointed to by the JpDX pa- 
rameter, whichever is greater. 


Example The Sitowa example uses the ExtTextOut function to clip text to a rectangular 
region defined by a RECT structure: 


RECT rc; 


SetRect(&rc, 90, 190, 250, 220); 


ExtTextOut(hdc, 100, 200, /* x and y coordinates * / 
ETO_CLIPPED, /* clips text to rectangle * / 
&rc, /* address of RECT structure */ 
"Test of ExtTextOut function.", /* string to write * / 
28, /* characters in string * / 
(LPINT) NULL); _ /* default character spacing: */ 
See Also GetBkColor, SetBkColor, SetTextAlign, SetTextColor, TabbedTextOut. 


TextOut 
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void FatalAppExit(fuAction, IpszMessageText) 
UINT fuAction; /* must be zero , ey 
LPCSTR IpszMessageText; /* string to display in message box *) 


_ The FatalAppExit function displays a message box and terminates the application 
_ when the message box is closed. If the user is running the debugging version of 
the Windows operating system, the message box gives the user the opportunity to 
terminate the application or to cancel the message box and return to the caller. 


Parameters fuAction 
Reserved; must be zero. 
IpszMessageText 
Points to a null-terminated string that is displayed in the message box. The mes- 


sage is displayed on a single line. To accommodate low-resolution screens, the 
string should contain no more than 35 characters. 


Return Value This function does not return a i value. 
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Comments An application should call the FatalAppExit function only when it is incapable of 
terminating any other way. FatalAppExit may not always free an application’s 
- memory or close its files, and it may cause a general failure of Windows. An appli- 
cation that encounters an unexpected error should terminate by freeing all its 
memory and returning from its main message loop. 


See Also | FatalExit, TerminateApp 


FatalExit 7 a 


void FatalExit(nErrCode) 
int nErrCode; /* error value to display os 


The FatalExit function sends the current state of Windows to the debugger and 
prompts for instructions on how to proceed. 


An application should call this function for debugging purposes only; it should not 
call the function in a retail version of the application. Calling this function in the 
retail version will terminate the application. 


Parameters nErrCode | 
Specifies the error value to be displayed. 


Return Value This function does not return a value. 


Comments The displayed information includes an error value followed by a symbolic stack 
trace, showing the flow of execution up to the point of the call. 


The FatalExit function prompts the user to respond to an Abort, Break, or Ignore 
message. Windows processes the response as follows: 


Response Description 

A (Abort) Terminate immediately. 
B (Break) Enter the debugger. 

I (ignore) Return to the caller. 


You can specify any combination of error values for the nErrCode parameter, 
since the meaning of the values is unique to your application. However, the error 
value —1 must always be reserved for the stack-overflow message. When this 
value is specified, Windows automatically displays a stack-overflow message. 


See Also | FatalA ppExit 


FillRect 
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[ 2.x J 


int FillRect(hdc, Iprc, hbr) 


HDC hdc; /* handle of device context if | 

const RECT FAR*® [prc; /* address of structure with rectangle | i 

HBRUSH hbr; /* handle of brush ow A 
The FillRect function fills a given rectangle by using the specified brush. The 
FillRect function fills the complete rectangle, including the left and top borders, 
but does not fill the right and bottom borders. 

Parameters hdc 


Return Value 


Comments 


See Also 


Identifies the device context. 


lpre 
Points to a RECT structure that contains the logical poondunates of the 
rectangle to be filled. The RECT structure has the following form: 


typedef struct tagRECT { /* ro x*/ 
int left; 3 
int top; 
int right; 
int bottom; 

} RECT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


hbr | 
Identifies the brush used to fill the rectangle. 


The return value is not used and has no meaning. 


The brush must be created by using either the CreateHatchBrush, Create- 
PatternBrush, or CreateSolidBrush function, or retrieved by using the Get- 
StockObject function. 


When filling the specified rectangle, the FillRect function does not include the rec- 
tangle’s right and bottom sides. Graphics device interface (GDI) fills a rectangle 
up to, but not including, the right column and bottom row, regardless of the cur- 
rent mapping mode. 


FillRect compares the values of the top, bottom, left, and right members of the — 
specified RECT structure. If bottom is less than or equal to top, or if right is less 
than or equal to left, the function does not draw the rectangle. 


CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, pero loca bec 
InvertRect 
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FillRgn 


BOOL FillRgn(hdc, hrgn, hbr) 


HDC hdc; 


HRGN hrgn; 
HBRUSH hbr; 


Parameters 


Return Value 


Example 


See Also 


/* handle of device context ey | 


/* handle of region | | 
/* handle of brush | 


The FillRgn function fills the given region by using the specified brush. 


hdc 7 
Identifies the device context. 
hrgn 
Identifies the region to be filled. The coordinates for the given eeton are 
specified in device units. 


hbr 
Identifies the brush to be used to fill the region. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The following example uses a blue brush to fill a rectangular region. Note that it is 
not necessary to select the brush into the device context before using it to fill the 
region. 


HRGN hrgn; 
HBRUSH hBrush; 


hrgn = CreateRectRgn(10, 10, 110, 110); 
SelectObject(hdc, hrgn); 


hBrush = CreateSolidBrush(RGB(Q, @, 255)); 


~ FillRgn(hdc, hrgn, hBrush); 


DeleteObject(hrgn); 


CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, 
CreatePatternBrush, CreateSolidBrush, PaintRgn 
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FindAtom | [ 2.x | 


ATOM FindAtom(IpszString) 
LPCSTR IpszString; /* address of string to find #/ 


The FindAtom function searches the local atom table for the specified character 
string and retrieves the atom associated with that string. 


Parameters IpszString 
Points to the null-terminated character string to search for. 


Return Value The return value identifies the atom associated with the given string if the function 
: _ is successful. Otherwise (if the string is not in the table), the return value is zero. 


Example | The following example uses the FindAtom function to retrieve the atom for the 
string “This is an atom”’: 


ATOM at; 
char szMsg[8@]; 


if ((at = FindAtom("This is an atom")) == Q) 
MessageBox(hwnd, "could not find atom", 
"FindAtom", MB_ICONEXCLAMATION); 

else { 
wsprintf(szMsg, “atom = %u", at); 
MessageBox(hwnd, szMsg, “FindAtom™", MB_OK); 
} 


See Also AddAtom, DeleteAtom 


FindExecutable ae [3.1 | 


#include <shellapi.h> 


HINSTANCE FindExecutable(/pszFile, lpszDir, IpszResult) i 
LPCSTR IpszFile; /* address of string for filename i 


LPCSTR [pszDir; /* address of string for default directory +} 


LPSTR [pszResult; /* address of string for executable file on return sf 


The FindExecutable function finds and retrieves the executable filename that is 
associated with a specified filename. | 
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Parameters 


Return Value 


Errors 


lpszFile 
Points to a null-terminated string specifying a filename. This can be a document 
or executable file. 


IpszDir 
Points to a null-terminated string specifying the drive letter and path for the ie 
fault directory. 


lpszResult 
Points to a buffer that receives the name of an executable file when the function 
returns. This null-terminated string specifies the application that is started when 
the Open command is chosen from the File menu in File Manager. 


The return value is greater than 32 if the function is successful. If the return value 
is less than or equal to 32, it specifies an error code. 


The FindExecutable function returns 31 if there is no association for the specified 
file type. The other possible error values are as follows: 


Value Meaning 
0 | System was out of memory, executable file was corrupt, or relocations were 
invalid. 
2 File was not found. 
3 Path was not found. 
5 Attempt was made to dynamically link to a task, or there was a sharing or 
network-protection error. 
6 Library required separate data segments for Bk task. 
8 There was insufficient memory to start the application. 
10 Windows version was incorrect. 
11 Executable file was invalid. Either it was not a Windows application or 
| there was an error in the .EXE image. 
12 Application was designed for a different operating system. 
13 Application was designed for MS-DOS 4.0. 
14 Type of executable file was unknown. 
15 Attempt was made to load a real-mode application (developed for an earlier 
version of Windows). | 
16 Attempt was made to load a second instance of an executable file contain- 
ing multiple data segments that were not marked read-only. 
19 Attempt was made to load a compressed executable file. The file must be | 
decompressed before it can be loaded. 
20 _ Dynamic-link library (DLL) file was invalid. One of the DLLs ee to 


run this application was corrupt. 
21 Application requires Microsoft Windows 32- bit extensions. 


FindResource 305 


Comments The filename specified in the /pszFile parameter is associated with an executable 
file when an association has been registered between that file’s filename extension 
and an executable file in the registration database. An application that produces 
files with a given filename extension typically associates the extension with an ex- 
ecutable file when the application is installed. 


See Also RegQuery Value, ShellExecute 


FindResource [2.x | 


HRSRC FindResource(hinst, [pszName, lpszType) 


HINSTANCE hinst; /* handle of module containing resource i!) 
LPCSTR [pszName; /* address of resource name */ 
LPCSTR IpszType; /* address of resource type a 


The FindResource function determines the location of a resource in the specified 
resource file. 


~ Parameters hinst | | 
Identifies the instance of the module whose executable file contains the re- 
source. 


lpszName 
Specifies the name of the resource. For details, see the following Comments 
section. . 


lpszType ~~ 
Specifies the resource type. For details, see the following Comments section. 
For predefined resource types, this parameter should be one of the following 


values: 
Value Meaning 
RT_ACCELERATOR Accelerator table 
RT_BITMAP | Bitmap resource 
RT_CURSOR | Cursor resource 
RT_DIALOG Dialog box 
RT_FONT Font resource 
RT_FONTDIR Font directory resource 
-RT_ICON Icon resource 
-  RT_MENU Menu resource | 
RT_RCDATA User-defined resource (raw data) 


RT_STRING _ String resource 
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Return Value 


Comments — 


See Also 


FindText 


The return value is the handle of the named resource if the function is successful. 


Otherwise, it is NULL. | 


“Tf the high-order word of the pszName or lpszType parameter is zero, the low- 


order word specifies the integer identifier of the name or type of the given re- 
source. Otherwise, the parameters are long pointers to null-terminated strings. If 
the first character of the string is a pound sign (#), the remaining characters repre- 
sent a decimal number that specifies the integer identifier of the resource’s name 
or type. For example, the string #258 represents the integer ID 258. 


To reduce the amount of memory required for the resources used by an applica- 
tion, the application should refer to the resources by integer identifier instead of by 
name. 


An application must not call the FindResource and LoadResource functions to 
load cursor, icon, and string resources. Instead, it must load these resources by 
calling the LoadCursor, LoadIcon, and LoadString functions, respectively. 


Although the application can call the FindResource and LoadResource functions 
to load other predefined resource types, it should load the corresponding resources 
by calling the LoadAccelerators, LoadBitmap, and LoadMenu functions. 


LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, 
LoadResource, LoadString 


#include <commdlg.h> 


HWND FindText(p/r) | 
FINDREPLACE FAR® Ipfr; /* address of structure with initialization data | 


Parameters 


The FindText function creates a system-defined modeless dialog box that makes 
it possible for the user to find text within a document. The application must per- 
form the search operation. 


lpfr 
Points to a FINDREPLACKE structure that contains information used to initial- 
ize the dialog box. When the user makes a selection in the dialog box, the sys- 
tem fills this structure with information about the user’s selection and then 
sends a message to the application. This message contains a a to the 
FINDREPLACE structure. 


The FINDREPLACE structure has the following form: 


Return Value 


Errors 


Comments 
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fHinclude <commdlg.h> 


typedef struct tagFINDREPLACE { /* fr */ 


DWORD ~1StructSize; 
HWND hwndOwner; 
HINSTANCE hInstance; 
DWORD Flags; 
LPSTR lpstrFindWhat; 
“LPSTR lTpstrReplaceWith; 
UINT wFindWhatLen; 
— UINT wReplaceWithLen; 
LPARAM 1CustData; | 
UINT ~~ (CALLBACK* IpfnHook)(HWND, UINT, WPARAM, LPARAM) ; 


LPCSTR IpTemplateName; 
} FINDREPLACE; © 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the window handle of the dialog box if the function is success- 
ful. Otherwise, it is NULL. An application can use this window handle to com- 
municate with or to close the dialog box. 


Use the CommDIgExtendedError function to retrieve the error value, which may 
be one of the following values: 


CDERR_FINDRES FAILURE. 


‘CDERR_INITIALIZATION | 


CDERR_LOCKRESFAILURE 
CDERR_LOADRESFAILURE 
CDERR_LOADSTRFAILURE 
CDERR_MEMALLOCFAILURE ~ 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK 
CDERR_NOTEMPLATE 
CDERR_STRUCTSIZE 
FRERR_BUFFERLENGTHZERO 


The dialog box procedure for the Find dialog box passes user requests to the 
application through special messages. The /Param parameter of each of these 
_ messages contains a pointer to a FINDREPLACE structure. The procedure sends 
_ the messages to the window identified by the hwndOwner member of the FIND- 


REPLACE structure. An application can register the identifier for these messages 


by specifying the “commdlg_ EE Spe string in a call to the Register- — 


COW Eee function. ee 
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For the TAB key to function correctly, any application that calls the FindText func- 
tion must also call the IsDialogMessage function in its main message loop. (The 
IsDialogMessage function returns a value that indicates whether messages are in- 
tended for the Find dialog box.) 


If the hook function (to which the IpfnHook member of the FINDREPLACE 
structure points) processes the WM_CTLCOLOR message, this function must re- 
turn a handle of the brush that should be used to paint the control background. 


Example The following example initializes a FINDREPLACE structure and calls the 
FindText function to display the Find dialog box: 


FINDREPLACE fr; 
/* Set all structure members to zero. */ 
memset(&fr, @, sizeof(FINDREPLACE)); 


_ fr. 1StructSize = sizeof (FINDREPLACE); 
fr.hwndOwner = hwnd; 
fr.JpstrFindWhat = szFindWhat; 
fr.wFindWhatLen = sizeof(szFindWhat) ; 


hDlg = FindText(&fr) ; 


break; 


In addition to initializing the members of the FINDREPLACKE structure 
and calling the FindText function, an application must register the special 
FINDMSGSTRING message and process messages from the dialog box. 


The following example registers the message by using the RegisterWindow- 
Message function: 


UINT uFindReplaceMsg; 
/* Register the FindReplace message. */ 


uFindReplaceMsg = RegisterWindowMessage(FINDMSGSTRING) ; 


After the application registers the FINDMSGSTRING message, it can process 
messages by using the Register WindowMessage return value. An application 
must check the FR_-DIALOGTERM bit in the Flags member of the FIND- 
REPLACE structure when it processes this message, as in the following ex- 
ample: 


LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam, 
LPARAM 1Param) : 


See Also 


FindWindow 
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static FINDREPLACE FAR* Ipfr; 


if (msg == uFindReplaceMsg) { 
lpfr = (FINDREPLACE FAR*) 1Param; 
SearchFile((BOOL) (Ilpfr->Flags & FR_DOWN), 

(BOOL) (lpfr->Flags & FR_MATCHCASE)); 

return Q; 

} 

SearchFile((BOOL) (lpfr->Flags & FR_DOWN), 
(BOOL) (Ipfr->Flags & FR_MATCHCASE)); 

return Q; 


} 


IsDialogMessage, Register WindowMessage, ReplaceText 


[ 2x | 


HWND FindWindow(IpszC lassName, lpszWindow) _ 
LPCSTR IpszClassName; /* address of class-name string os 
LPCSTR IpszWindow; ——s/* address of window-name string = */ 


Parameters 


- Return Value 


Example 


‘See Also 


The Find Window function retrieves the handle of the window whose class name 
and window name match the specified strings. This function does not search child 
windows. _ | | 7 


lpszClassName — | | 
Points to a null-terminated string that contains the window’s class name. If this 
- parameter is NULL, all class names match. 


IpszWindow ee 
Points to a null-terminated string that specifies the window name (the window’s 
title). If this parameter is NULL, all window names match. 


The return value is the handle of the window that has the specified class name and 
window name if the function is successful. Otherwise, it is NULL. 


The following example searches for the main window of Windows Control Panel | 
(CONTROL.EXE) and, if it does not find it, starts Control Panel: 


if (FindWindow("CtlPanelClass"”, "Control Panel") == NULL) 
WinExec("control.exe", SW_SHOWNA) ; 7 


-EnumWindows, GetWindow, WindowFromPoint 
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FlashWindow 7 Pax] 


BOOL FlashWindow(hwnd, fInvert) 
HWND hwnd; /* handle of window to flash | 
BOOL finvert; /* invert flag ee | 


The Flash Window function flashes the given window once. Flashing a window 
means changing the appearance of its title bar as if the window were changing 
from inactive to active status or vice versa. (An inactive title bar changes to an ac- 
tive title bar or an active title bar changes to an inactive title bar.) 


Typically, a window is flashed to inform the user that the window requires atten- 
tion but that it does not currently have the input focus. 


Parameters hwnd 

3 Identifies the window to be flashed. The window can be either open or min- 

imized. 3 
finvert 

Specifies whether to flash the window or return it to its original state. If this 
parameter is TRUE, the window is flashed from one state to the other. If the pa- 
rameter is FALSE, the window is returned to its original state (either active or 
inactive). 


Return Value The return value is nonzero if the window was active before the call to the Flash- 
Window function. Otherwise, it is zero. 


Comments The Flash Window function flashes the window only once; for successive flash- 
_ ing, the application should create a system timer. 


The fInvert parameter should be FALSE only when the window is receiving the 
input focus and will no longer be flashing; it should be TRUE on successive calls 
while waiting to get the input focus. 


This function always returns nonzero for minimized windows. If the window is 
minimized, FlashWindow simply flashes the window’s icon; fInvert is ignored | 
for minimized windows. : 


See Also MessageBeep 


FloodFill 
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[ 2.x | 


BOOL FloodFill(hdc, nXStart, nYStart, clrref) 


HDC hdc; 
int nXStart; 
int nYStart; 


COLORREF clrref; 


Parameters 


Return Value 


Comments 


See Also 


FlushComm = 


/* handle of device context **/ 
/* x-coordinate of starting position a 
/* y-coordinate of starting position 7] 
/* color of fill boundary sy 


The Flood Fill function fills an area of the screen surface by using the current 
brush. The area is assumed to be bounded as specified by the clrref parameter. The 
FloodFill function begins at the point specified by the nXStart and nYStart parame- 
ters and continues in all directions to the color boundary. 


hdc 
Identifies the device context. 


nX Start 
Specifies the logical x-coordinate at which to begin filling. 


nY Start 
Specifies the logical y-coordinate at which to begin filling. 


clrref 
Specifies the color of the boundary. 


The return value is nonzero if the function is successful. Otherwise, it is zero, indi- 
cating that the filling cannot be completed, that the given point has the boundary 
color specified by clrref, or that the point is outside the clipping region. 


Only memory device contexts and devices that support raster-display technology 


‘support the FloodFill function. For more information about raster capabilities, see 


the description of the GetDeviceCaps function. 


ExtFloodFill, GetDeviceCaps _ 


[2x] 


int FlushComm(idComDev, fnQueue) 


int idComDev; 


int fnQueue; 


[* communications-device identifier i ae 
bs queue to flush - A) 3 


The FlushComm fiichon flushes all chatacters from the transmission or receiv- 
ing queue of the specified communications device. | 
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Parameters 


Return Value 


See Also 


FMExtensionProc 


#include <wfext.h> 


idComDev 
Specifies the communication device to be flushed. The i function 
returns this value. 


jnQueue 


Specifies the queue to be flushed. If this parameter is zero, the transmission 
queue is flushed. If the parameter is 1, the receiving queue is flushed. 


The return value is zero if the function is successful. It is less than zero if idCom- 
Dev is not a valid device or if fnQueue is not a valid queue. The return value is 
positive if there is an error for the specified device. For a list of the possible error 
values, see the GetCommError function. 


GetCommError, OpenComm 


HMENU FAR PASCAL FMExtensionProc(hwnd, wMsg, lParam) 
+ / 


HWND hwnd; 
WORD wMszg; 
LONG [Param; 


Parameters 


/* handle of the extension window 
/* menu-item identifier or message * / 
/* additional message information */ 


The FMExtensionProc function, an application-defined callback function, 
processes menu commands and messages sent to a File Manager extension — 
dynamic-link library (DLL). 


hwnd 
Identifies the File Niinaeer window. An extension DLL should use this handle 
to specify the parent for any dialog boxes or message boxes that the DLL may 
display and to send request messages to File Manager. 


wMs 
Specifies the message. This parameter may be one of the following values: 
Value Meaning 
1-99 Identifier for the menu item that the user 

| selected. 

FMEVENT_INITMENU User selected the extension’s menu. 
FMEVENT_LOAD File Manager is loading the extension DLL. 
FMEVENT_SELCHANGE | Selection in File Manager’s directory window, 


or Search Results window, changed. 
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Value — Meaning | | 
FMEVENT_UNLOAD File Manager is unloading the extension DLL. 
FMEVENT_USER_ REFRESH User chose the Refresh command from the Win- 
dow menu. 
lParam 


Specifies 32 bits of additional message-dependent information. 


Return Value _ The callback function should return the result of the message processing. The ac- 
| tual return value depends on the message that is processed. 


Comments Whenever File Manager calls the FMExtensionProc function, it waits to refresh 
its directory windows (for changes in the file system) until after the function re- | 
turns. This allows the extension to perform large numbers of file operations 
without excessive repainting by the File Manager. The extension does not need to 
send the FM_REFRESH_WINDOWS message to notify File Manager to repaint | 
its windows. | 


FrameRect = Ea 


int FrameRect(hdc, Iprc, hbr) | 
HDC hdc; /* handle of device context “| 


const RECT FAR* Iprc;_ _—s/* address of structure with rectangle */ 


HBRUSH hbr; /* handle of brush =] 


_ The FrameRect function draws a border around a rectangle, using the specified 
brush. The width and height of the border are always one logical unit. 


Parameters hdc : 
Identifies the device context in which to draw the border. 


lpre | 
Points to a RECT structure that contains the logical coordinates of the upper- 
left and lower-right corners of the rectangle. The RECT structure has the fol- 
lowing form: 


typedef struct tagRECT { /* ro */ 
int left; bee oan 
int top; 
int right;. 
int bottom; 
} RECT; 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hbr 
Identifies the brush that will be used to draw the border. 


Return Value The return value is not used and has no meaning. 


Comments The border drawn by the FrameRect function is in the same position as a border 

| drawn by the Rectangle function using the same coordinates (if Rectangle uses a 
pen that is one logical unit wide). The interior of the rectangle is not filled when 
an application calls FrameRect. 


FrameRect compares the values of the top, bottom, left, and right members of 
the specified RECT structure. If bottom is less than or equal to top, or if right is 
less than or equal to left, FrameRect does not draw the rectangle. 


See Also CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DrawFocusRect 


FrameRgn [2x | 


-BOOL FrameRegn(hdc, hrgn, hbr, nWidth, nHeight) 


HDC hdc; /* handle of device context | 
HRGN hrgn; /* handle of region oa 
HBRUSH hbr; _s/* handle of brush o 
int nWidth; /* width of region frame *] 
int nHeight; i height of region frame sa 
The FrameRgn function draws a border around the given region, using the 
specified brush. 
Parameters hdc 
Identifies the device context. 
hrgn | 
Identifies the region to be enclosed i in a border. 
hbr 
Identifies the brush to be used to draw the border. 
nWidth 
_ Specifies the width, in device units, of vertical brush ieciee 
nHeight 


Specifies the height, in device units, of horizontal brush strokes. 


Return Value 


Example 


See Also 
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The return value is nonzero if the function is successful. Otherwise, it iS zero. 


The following example uses a blue brush to frame a rectangular region. Note that 
it is not necessary to select the brush or the region into the device context. 


HRGN hrgn; 
HBRUSH hBrush; 
int Width = 5, Height = 2; 


hrgn 


= CreateRectRgn(10, 10, 110, 110); 
hBrush = 


CreateSolidBrush(RGB(@, @, 255)); 
FrameRgn(hdc, hrgn, hBrush, Width, Height); 


DeleteObject(hrgn); 
DeleteObject(hBrush); 


FillRgn, PaintRgn 


FreeAllGDIMem | [3.1 | 


#include <stress.h> 


void FreeAllGDIMem(void) 


Parameters 
Return Value 


See Also 


The FreeAllGDIMem function frees all memory allocated by the AllocGDIMem 
function. 


This function has no parameters. 


This function does not return a value. 


AllocGDIMem 


316. FreeAllMem 


FreeAllMem far 


#include <stress.h> 
void FreeAllMem(void) 


The FreeAliMem function frees all memory allocated by the AllocMem function. 


Parameters _ This function has no parameters. 
Return Value This function does not return a value. 
See Also AllocMem 


FreeAllUserMem oa 


#include <stress.h> 
void FreeAllUserMem(void) 


The FreeAllUserMem function frees all memory allocated by the AllocUserMem 


function. 
Parameters This function has no parameters. 
Return Value This function does not ei a value. 
See Also AllocUserMem 


FreeLibrary “er =P, heen 


void FreeLibrary(hinst) 
HINSTANCE hinst; /* handle of loaded library module */ 


The FreeLibrary function decrements (decreases by one) the reference count of | 
the loaded library module. When the reference count reaches zero, the memory oc- 
cupied by the module is freed. 


Parameters 


Return Value 


Comments 


Example 


See Also 


FreeModule 


FreeModule ~—6317 


hinst 
Identifies the loaded library module. 


This function does not return a value. 


A dynamic-link library (DLL) must not call the FreeLibrary function within its 
WEP function (Windows exit procedure). 


The reference count for a library module is incremented (increased by one) each 
time an application calls the LoadLibrary function for the library module. 


The following example uses the LoadLibrary function to load TOOLHELP. DLL 
and the FreeLibrary function to free it: 


HINSTANCE hinstToolHelp = LoadLibrary("TOOLHELP.DLL") ; 
if ((UINT) hinstToolHelp > 32) { 


. /* use GetProcAddress to use TOOLHELP functions */ 


} 

else { 
ErrorHandler(); 

} 


if ((UINT) hinstToolHelp > 32) | 
FreeLibrary(hinstToolHelp); /* free TOOLHELP.DLL * / 


GetProcAddress, LoadLibrary, WEP 


BOOL FreeModule(hinst) 


HINSTANCE hinst; 


Parameters 


Return Value 


_ /* handle of loaded module */ 


The FreeModule function decrements (decreases by one) the reference count of 
the loaded module. When the reference count reaches zero, the memory occupied 
by the module is freed. 


hinst 
Identifies the loaded module. 


The return value is zero if the reference count is decremented to zero and the mod- 
ule’s memory is freed. Otherwise, the return value is nonzero. 


318 FreeProcinstance 


Comments The reference count for a module is incremented (increased by one) each time an 
application calls the LoadModule function for the module. 


See Also LoadModule 


FreeProcinstance  —s_—it oe 


void FreeProcInstance(/pProc) 
FARPROC I[pProc; /* instance address of function to free **/ 


The FreeProcInstance function frees the specified function from the data seg- 
ment bound to it by the MakeProclInstance function. 


Parameters IpProc | 
| Points to the procedure-instance address of the function to be freed. It must be 
created by using the MakeProcInstance function. 


Return Value This function does not return a value. 


Comments After a procedure instance has been freed, attempts to call the function using the 
freed procedure-instance address will result in an unrecoverable error. 


See Also MakeProcInstance 


FreeResource | | [ex] 


BOOL FreeResource(hglbResource) 
~ HGLOBAL helbResource; /* handle of loaded resource a) 


__ The FreeResource function decrements (decreases by one) the reference count of 
a loaded resource. When the reference count reaches zero, the memory occupied 
by the resource is freed. 


Parameters | hglbResource — | oes 
Identifies the data associated with the resource. The handle is assumed to have 
been created by using the LoadResource function. 


Return Value 


Comments 


See Also 


FreeSelector 


GetActiveWindow 319 
The return value is zero if the function is successful. Otherwise, it 1s nonzero, indi- 


cating that the function has failed and the resource has not been freed. 


The reference count for a resource is incremented (increased by one) each time an 
application calls the LoadResource function for the resource. 


LoadResource 


UINT FreeSelector(uSelector) 


UINT uSelector; 


Parameters 
Return Value 


See Also 


/* selector to be freed */ 


The FreeSelector function frees a selector originally allocated by the Alloc- 


Selector or AllocDStoCSAlias function. After the apphcauon calls this function, 


the selector is invalid and must not be used. 


_ An application should not use this function unless it is absolutely necessary, since 


its use violates preferred Windows programming practices. 


—uSelector 


Specifies the selector to be freed. 


The return value is zero if the function is successful. Otherwise, it is the selector 
specified by the uSelector parameter. 


AllocDStoCSAlias, AllocSelector 


GetActiveWindow 


HWND GetActiveWindow(void) 


Parameters 


The GetActiveWindow function retrieves the window handle of the active win- 
dow. The active window is either the top-level window associated with the input: 
focus or the window explicitly made active by the SetActive Window function. 


This function has no parameters. 
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Return Value The return value is the handle of the active window or NULL if no window was ac- 
tive at the time of the call. ” 


See Also GetCapture, GetFocus, GetLastActivePopup, SetActiveWindow 


GetAspectRatioFilter 2x | 


DWORD GetAspectRatioFilter (hdc) 
HDC hdc; /* handle of device context */ 


The GetAspectRatioFilter function retrieves the setting for the current aspect- 
ratio filter. The aspect ratio is the ratio formed by a device’s pixel width and 
height. Information about a device’s aspect ratio is used in the creation, selection, 
and display of fonts. Windows provides a special filter, the aspect-ratio filter, to 
select fonts designed for a particular aspect ratio from all of the available fonts. 
The filter uses the aspect ratio specified by the SetMapperFlags function. 


Parameters hdc 
Identifies the device context that contains the specified aspect ratio. 


Return Value _ The low-order word of the return value contains the x-coordinate of the aspect 
ratio if the function is successful; the high-order word contains the y-coordinate. 


See Also SetMapperFlags 


GetAspectRatioFilterEx fa 


BOOL GetAspectRatioFilterEx(hdc, [pAspectRatio) 
HDC hdc; 
SIZE FAR* [pAspectRatio; 


The GetAspectRatioFilterEx function retrieves the setting for the current aspect- 

~ ratio filter. The aspect ratio is the ratio formed by a device’s pixel width and 
height. Information about a device’s aspect ratio is used in the creation, selection, 
and displaying of fonts. Windows provides a special filter, the aspect-ratio filter, 
to select fonts designed for a particular aspect ratio from all of the available fonts. 
The filter uses the aspect ratio specified by the SetMapperF lags function. 
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Parameters hDC 
Identifies the device context that contains the specified aspect ratio. 
lpAspectRatio 
Pointer to a SIZE structure oe the current aspect ratio filter will be returned. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
See Also SetMapperFlags 


GetAsyncKeyState [2x | 


int GetAsyncKeyState(vkey) 
int vkey; /* virtual-key code a 


The GetAsyncKeyState function determines whether a key is up or down at the 
time the function is called and whether the key was pressed after a previous call to 
the GetAsyncKeyState function. 


Parameters vkey 
Specifies one of 256 possible virtual- key codes. 


Return Value The return value specifies whether the key was pressed since the last call to the © 
| GetAsyncKeyState function and whether the Key is currently up or down. If the 
most significant bit is set, the key is down, and if the least significant bit is set, the 
key was pressed after a preceding GetAsyncKeyState call. 


Comments If VK_LBUTTON or VK_RBUTTON is specified in the vkey parameter, this func- 
tion returns the state of the physical left or right mouse button regardless of 
whether the SwapMouseButton function has been used to reverse the meaning of 
the buttons. , 


See Also GetKeyboardState, GetKeyState, SetKeyboardState, SwapMouseButton 
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GetAtomHandle 


HLOCAL GetAtomHandle(atm) _ 
ATOM atm; ___/* atom to retrieve handle of */ 


Parameters 


Return Value 


See Also 


GetAtomName 


atm 


The GetAtomHandle function retrieves a handle of the specified atom. 


This function is only provided for compatibility with Windows, versions 1.x and 
2.x. It should not be used with Windows 3.0 and later. 


Specifies an atom whose handle is to be retrieved. 


The return value is a handle of the specified atom if the function is successful. 


GetAtomName, GlobalGetAtomName 


UINT GetAtomName(aim, lpszBuffer, cbBuffer) 


ATOM atm; 
LPSTR [pszBuffer; 
int cbBuffer; 


Parameters 


Return Value 


‘Comments 


/* atom identifying character string sy 
/* address of buffer for atom string */ 
/* size of buffer >] 


The GetAtomName function retrieves a copy of the character string associated 
with the specified local atom. 


atm : 
Specifies the local atom that identifies the character string to be retrieved. | 


lpszBuffer 
Points to the buffer for the character string. 


cbBuffer 


Specifies the maximum size, in bytes, of the buffer. 


The return value specifies the number of bytes copied to the buffer, if the function 
1S successful. 


The string returned for an integer atom (an atom created by the MAKEINT- 
ATOM macro) will be a null-terminated string, where the first character is a 
pound sign (#) and the remaining characters make up the UINT used in MAKE- 
INTATOM. 
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Example The following example uses the GetAtomName function to retrieve the character 
string associated with a local atom: 


char szBuf[80]; 
GetAtomName(atTest, szBuf, sizeof(szBuf)); 


MessageBox(hwnd, szBuf, "GetAtomName", MB_OK); 


See Also AddAtom, DeleteAtom, FindAtom 


GetBitmapBits ieee Rae eee: 


LONG GetBitmapBits(ibm, cbBuffer, lpvBits) | 
HBITMAP hbm; /* handle of bitmap a 


LONG chBuffer; /* number of bytes to copy to buffer ae 
void FAR* [pvBits; /* address of buffer for bitmap bits a 


The GetBitmapBits function copies the bits of the specified bitmap into a buffer. _ 


Parameters hbm- | 
: __ Identifies the bitmap. 


cbBuffer | 
Specifies the number of bytes t to be copied. 


lpvBits i 

Points to the buffer that is to receive the bitmap. The bitmap is an array ae 
bytes. This array conforms to a structure in which horizontal scan lines are 
multiples of 16 bits. . 


ReturnValue = =‘ The return value specifies the number of bytes in the bitmap if the function 1S 
| successful. It is zero if there is an error. | | 


Comments == — An application can use the GetObject function to deeaniae the number of bytes 
oo - to copy into the buffer pointed to by dl the kes patameler, 


See Also GetObject, SetBitmapBits _ 
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GetBitmapDimension Ea 


DWORD GetBitmapDimension(hbm) 
HBITMAP hbm; ___/* handle of bitmap */ 


The GetBitmapDimension function returns the width and height of the specified 
bitmap. The height and width is assumed to have been set by the SetBitmap- 


Dimension function. 
Parameters hbm 
Identifies the bitmap. 
Return Value The low-order word of the return value contains the bitmap width, in tenths of a 


millimeter, if the function is successful; the high-order word contains the height. If 
the bitmap width and hei ght have not been set by using the SetBitmapDimension 
function, the return value is zero. 


See Also SetBitmapDimension 


GetBitmapDimensionEx [2x | 


BOOL GetBitmapDimensionEx(/Bitmap, lpDimension) | 
HBITMAP hBitmap; /* handle of bitmap */ 
SIZE FAR* [pDimension; /* address of dimension structure ms | 


The GetBitmapDimensionEx function returns the dimensions of the bitmap pre- 
viously set by the SetBitmapDimensionEx function. If no dimensions have been 
set, a default of 0,0 will be returned. 


Parameters hBitmap 
Identifies the bitmap. 


[pDimension 
Points to a SIZE structure to which the dimensions are returned. The SIZE 
structure has the following form: 


typedef struct tagSIZE { 
int cx; 
int cy; 

} SIZE; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value 


See Also 


GetBkColor 
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The return value is nonzero if the function is successful. Otherwise, it is zero. 


SetBitmapDimensionEx 


COLORREF GetBkColor(hdc) 


HDC hdc; 


Parameters 
Return Value 


Comments 


Example 


See Also 


/* handle of device context **/ 


The GetBkColor function returns the current background color. 


hdc , 
Identifies the device context. 


The return value is an RGB (red, green, blue) color value if the function is suc- 
cessful. 


If the background mode is OPAQUE, the system uses the background color to fill 
the gaps in styled lines, the gaps between hatched lines in brushes, and the back- 
ground in character cells. The system also uses the background color when con- 
verting bitmaps between color and monochrome device contexts. 


The following example uses the GetBkColor function to determine whether the 


current background color is white. If it is, the SetBkColor function sets it to red. 


DWORD dwBackColor; 


dwBackColor = GetBkColor(hdc); * 

if (dwBackColor == RGB(255, 255, 255)) { /* if color is white */ 
SetBkColor(hdc, RGB(255, @, @)); /* sets color to red */ 
TextOut(hdc, 100, 200, "SetBkColor test.", 16);— 7 : 

} | 


GetBkMode, SetBkColor, SetBkMode 
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GetBkMode ~ a 2x | 


int GetBk Mode (hdc) 
HDC hdc; __—s/* handle of device context sf 


The GetBkMode function returns the background mode. The background mode 
defines whether the system removes existing background colors on the drawing 
surface before drawing text, hatched brushes, or any pen style that is not a solid 
line. 


Parameters hdc | 
| Identifies the device context. 


Return Value The return value specifies the current background mode if the function is success- 
ful. It can be OPAQUE, TRANSPARENT, or TRANSPARENT. 


Example The following example determines the current background mode by calling the 
GetBkMode function. If the mode is OPAQUE, the SetBkMode function sets it 
to TRANSPARENT. 


int nBackMode; 

nBackMode = GetBkMode(hdc); 

if (nBackMode == OPAQUE) { | 
TextOut(hdc, 90, 100, "This background mode is OPAQUE.", 31); 


SetBkMode(hdc, TRANSPARENT) ; 
} ; 


see Also GetBkColor, SetBkColor, SetBkMode 


GetBoundsRect rai 


UINT GetBoundsRect(hdc, lprcBounds, flags) 


HDC hdc; /* handle of device context ia | 
RECT FAR®* IprcBounds; /* address of structure for bounding rectangle =| 
UINT flags; /* specifies information to return a 


The GetBoundsRect function returns the current accumulated bounding rectangle 
for the specified device context. 


a 


Parameters 


Return Value 


Comments 


See Also 


GetBrushOrg 
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hdc ne | 
Identifies the device context to return the bounding rectangle for. 


lprcBounds 
Points to a buffer that will receive the current bounding rectangle. The rectangle 
is returned in logical coordinates. 


flags 
Specifies whether the bounding rectangle is to be cleared after it is returned. 
This parameter can be DCB_RESET, to clear the rectangle. Otherwise, it 
should be zero. 


The return value is DCB_SET if the bounding rectangle is not empty. Oierwiee 
itis DCB RESET. 


To ensure that the bounding rectangle is empty, check both the DCB_RESET bit 
and the DCB_ACCUMULATE bit in the return value. If DCB_RESET is set and 
DCB_ACCUMULATE is not, the bounding rectangle is empty. ) 


SetBoundsRect 


DWORD GetBrushOrg(hdc) 


HDC hdc; 


Parameters 


Return Value 


/* handle of device context =) 


The GetBrushOrg futhotion retrieves the origin, in device coordinates, of the | 
brush currently selected for the given device context, 


hdc 
Identifies the device context. 


The low-order word of the return value contains the current x-coordinate of the 
brush, in device coordinates, if the function is successful; the high- -order word con- 
tains the y-coordinate. 
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Comments ~The initial brush origin is at the coordinates (0,0) in the client area. The return 


value specifies these coordinates in device units relative to the origin of the desk- 
top window. 


Example The following example uses the LOWORD and HIWORD macros to extract the 
| x- and y-coordinate of the current brush from the return value of the GetBrush- © 
Org function: 


DWORD dwBrOrg; 
WORD wXBrOrg, wYBrOrg; 


dwBrOrg = GetBrushOrg(hdc); 

wXBrOrg = LOWORD(dwBrOrg); 

wYBrOrg = HIWORD(dwBrOrg); 
See Also  SelectObject, SetBrushOrg 


GetBrushOrgEx [3.1 | 


BOOL GetBrushOrgEx(hDC, [pPoint) 
HDC hDC; /* handle of device context */ 
POINT FAR® [pPoint; /* address of structure for brush origin +) 


The GetBrushOrgEx function retrieves the current brush origin for the given 
device context. 


Parameters hDC 
Identifies the device context. 
[pPoint | : 
Points to a POINT structure to which the device coordinates of the brush origin 
are to be returned. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. : 
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Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The initial brush origin is at the coordinate (0,0). 
See Also SetBrushOrg 


GetCapture [2.x | 
HWND GetCapture(void) | 


The GetCapture function retrieves a handle of the window that has the mouse 
capture. Only one window has the mouse capture at any given time; this window: 
receives mouse input whether or not the cursor is within its “borders. | | 


Parameters This function has no parameters. 


Return Value The return value is a handle identifying the window that has the mouse capture if 
the function is successful. It is NULL if no window has the mouse capture. 


~ Comments | A window receives the mouse capture when its handle is passed as the hwnd pa- 
rameter of the SetCapture function. 


See Also SetCapture 


GetCaretBlinkTime eS Bae 
UINT ee te 


The GetCaretBlinkTime function retrieves the caret blink rate. The blink rate is 
; the elapsed time, in milliseconds, between flashes of the caret. 


Parameters | This function has no parameters. 


330 GetCaretPos 


Return Value The return value peiten the blink rate, in milliseconds, if the function i 1S 
successful. 
See Also SetCaretBlinkTime 


GetCaretPos xd 


void GetCaretPos(/ppt) 
POINT FAR® Ippt; /* address of structure to receive coordinates **/ 


The GetCaretPos function retrieves the current position of the caret. 


Parameters [ppt 
Points to a POINT structure that receives the client coordinates of the caret’s 
current position. The POINT structure has the following form: 
typedef struct tagPOINT { /* pt */ 
int x; 
int y; 
} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


Comments The caret position is always given in the client coordinates of the window that con- 
tains the caret. 


See Also SetCaretPos 


GetCharABCWidths ca 


BOOL GetCharABCWidths(hdc, uFirstChar, uLastChar, Ipabc) 
*/ 


HDC hdc; /* handle of device context 
UINT uFirstChar; /* first character in range to query i) 
UINT uLastChar; /* last character in range to query =) 


LPABC Ipabc; /* address of ABC width structures */ 


Parameters 


Return Value 


Comments | 


See Also 
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The GetCharA BC Widths function retrieves the widths of consecutive characters 
in a specified range from the current TrueType font. The widths are returned in 
logical units. This function succeeds only with TrueType fonts. 


hdc . 
Identifies the device context. 
uFirstChar 


Specifies the first character in the range of characters from the current font for 
which character widths are returned. 7 


uLastChar 
Specifies the last character in the range of characters from the current font for 
which character widths are returned. 


lpabc 
Points to an array of ABC structures that receive the character widths when the 
function returns. This array must contain at least as many ABC structures as 
there are characters in the range specified by the uFirstChar and uLastChar pa- 
rameters. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The TrueType rasterizer provides ABC character spacing after a specific point size 
has been selected. “A” spacing is the distance that is added to the current position 
before placing the glyph. “B” spacing is the width of the black part of the glyph. 
“C”’ spacing is added to the current position to account for the white space to the 
right of the glyph. The total advanced width is given by A+B +C. 


When the GetCharA BC Widths function retrieves negative “A” or “C” widths for 
a character, that character includes underhangs or overhangs. 


To convert the ABC widths to font design units, an application should create a 
font whose height (as specified in the lfHeight member of the LOGFONT struc- 
ture) is equal to the value stored in the ntmSizeEM member of the NEWTEXT- 
METRIC structure. (The value of the ntmSizeEM member can be retrieved by 
calling the EnumFontFamilies function.) 


The ABC widths of the default character are used for characters that are outside 
the range of the currently selected font. 


_ To retrieve the widths of characters in non-TrueType fonts, ce should 


use the GetChar Width function. 


EnumFontFamilies, GetCharWidth 
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GetCharWidth 


BOOL GetCharWidth(hdc, uFirstChar, uLastChar, lpnWidths) 


HDC hdc; 

UINT uFirstChar; 
UINT uLastChar; 
int FAR* [pnWidths; 


Parameters 


Return Value 


Comments 


Example 


/* handle of device context */ 
/* first character in range to query */ 
/* last character in range to query */ 
/* address of buffer for widths si 


The GetCharWidth function retrieves the widths of individual characters in a 
range of consecutive characters in the current font. 


hdc 
Identifies the device context. 


uFirstChar 
Specifies the first character in a group of consecutive characters in the current 
font. 


uLastChar : 
Specifies the last character i in a group of consecutive characters in the current 
font. 


[pnWidths 
Points to a buffer that receives the width values for a group of consecutive char- 
acters in the current font. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


If a character in the group of consecutive characters does not exist in a particular 
font, it will be assigned the width value of the default character. 


The following example uses the GetChar Width function to retrieve the widths of 
the characters from “T’ through “S” and aspiays the total number of widths re- 
trieved in a message box: 


HDC hdc; 

WORD wlotalValues; 

WORD wFirstChar, wLastChar; 
int InfoBuffer[256]; 

char szMessage[30]; 


wFirstChar = (WORD) '‘'I'; 
wLastChar = (WORD) '‘'S'; 


hdc = GetDC(hwnd); 
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if (GetCharWidth(hdc, wFirstChar, wLastChar, (int FAR*) InfoBuffer)) { 
wlotalValues = wLastChar - wFirstChar + 1; 
wsprintf(szMessage, "Total values received: %d", wlotalValues); 
MessageBox(hwnd, szMessage, "GetCharWidth", MB_OK); — 

} 

else . 
MessageBox(hwnd, “GetCharWidth was unsuccessful", "ERROR!", 

MB_OK); | 


ReleaseDC(hwnd, hdc); 


See Also GetCharABCWidths 


GetClassinfo = 


BOOL GetClassInfo(hinst, lpszClassName, Ipwc) 


HINSTANCE hinst; /* handle of application instance — **/ 
LPCSTR lpszClassName; /* address of class-name string a th 
WNDCLASS FAR®* [pwc; /* address of structure for class data st) 


The GetClassInfo function retrieves information about a window class. This func- 
tion is used for creating subclasses of a given class. 


Parameters hinst 
Identifies the instance of the application that created the class. To retrieve infor- 
mation about classes defined by Windows (such as buttons or list boxes), set 
this parameter to NULL. 


lpszClassName 
Points to a null-terminated string containing the class name. The class name is 
either an application-specified name as defined by the RegisterClass function 
or the name of a preregistered window class. If the high-order word of this pa- 
rameter is NULL, the low-order word is assumed to be a value returned by the 
MAKEINTRESOURCE macro used when the class was created. 


lpwc 
Points toa WNDCLASS structure that receives the information about ns class. 
The WNDCLASS structure has the following form: 


typedef struct tagWNDCLASS { /* wo */ 


UINT style; 

WNDPROC JpfnWndProc; 
int cbClsExtra; 
int cbWndExtra; 


HINSTANCE hInstance; 
HICON hIcon; 
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HCURSOR ~=hCursor; 

HBRUSH hbrBackground; 

LPCSTR lpszMenuName; 

LPCSTR lpszClassName; 
} WNDCLASS; — 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero, indi- 
cating the function did not find a matching class. 


Comments The GetClassInfo function does not set the IlpszClassName and IpszMenuName 
members of the WNDCLASS structure. The menu name is not stored internally 
and cannot be returned. The class name is already known, since it is passed to this 
function. GetClassInfo returns all other members with the values used when the 
class was registered. 


See Also GetClassLong, GetClassName, GetClassWord, RegisterClass 


GetClassLong Ta 


LONG GetClassLong(hwnd, offset) 
HWND hwnd; /* handle of window a 
int offset; /* offset of value to retrieve */ 


The GetClassLong function retrieves a 32-bit (long) value at the specified offset 
into the extra class memory for the window class to which the given window 
belongs. Extra class memory is reserved by specifying a nonzero value in the 
cbCIsExtra member of the WNDCLASS structure used with the RegisterClass 
function. | | 


Parameters _ hwnd 
: | Identifies the window. 


offset | 
Specifies the zero-based byte offset of the value to be retrieved. Valid values 
are in the range zero through the number of bytes of class memory minus four 
(for example, if 12 or more bytes of extra class memory was specified, a value 
of 8 would be an index to the third 32-bit integer) or one of the following 
values: 
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Value Meaning 


GCL_MENUNAME Retrieves a 32-bit pointer to the menu-name string. 


GCL_WNDPROC Retrieves a 32-bit pointer to the window procedure. 

Return Value The return value is the specified 32-bit value in the extra class memory if the func- 
tion is successful. Otherwise, it is zero, indicating the hwnd or offset parameter is 
invalid. 

Comments To access any extra four-byte values allocated when the window-class structure 


was created, use a positive byte offset as the index specified by the offset parame- 
ter, starting at 0 for the first four-byte value in the extra space, 4 for the next four- 
byte value, and so On. 


See Also GetClassInfo, GetClassName, GetClassWord, RegisterClass, SetClassLong 


GetClassName oe Ba 


int GetClassName(hwnd, lpszClassName, cchClassName) 


HWND hwnd; /* handle of window | 
LPSTR IpszClassName; /* address of buffer for class name */ 
int cchClassName; /* size of buffer */ 


The GetClassName function retrieves the class name of a window. 


Parameters _ hwnd 
Identifies the window. 


lpszClassName 
Points to a buffer that receives the null-terminated class name string. 


cchClassName 
Specifies the length of the buffer pointed to by the [pszClassName parameter. 
The class name string is truncated if it is longer than the buffer. - 


Return Value The return value is the length, in bytes, of the returned class name, not including 
- the terminating null character. The return value is zero if the specified window 
handle is invalid. 
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GetClassWord - + . Ea 


WORD GetClassWord(hwnd, offset) 


HWND hwnd; 
int offset; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of window */ 
/* offset of value to retrieve */ 


The GetClass Word function retrieves a 16-bit (word) value at the specified offset 
into the extra class memory for the window class to which the given window 
belongs. Extra class memory is reserved by specifying a nonzero value in the 
cbClsExtra member of the WNDCLASS structure used with the RegisterClass 
function. | | 


hwnd 
Identifies the window. 


offset 


Specifies the zero-based byte offset of the value to be retrieved. Valid values 

are in the range zero through the number of bytes of class memory minus two 
(for example, if 10 or more bytes of extra class memory was specified, a value 
of 8 would be an index to the fifth 16-bit integer) or one of the following values: 


Value Meaning 


GCW_CBCLSEXTRA _— Retrieves the number of bytes of additional class 
information. For information about how to access 
this memory, see the following Comments section. 
GCW_CBWNDEXTRA Retrieves the number of bytes of additional win- 
| dow information. For information about how to 
access this memory, see the following Comments 


section. 
GCW_HBRBACKGROUND Retrieves the handle of the background brush. 
GCW_HCURSOR Retrieves the handle of the cursor. 
GCW_HICON Retrieves the handle of the icon. 
GCW_HMODULE Retrieves the handle of the module. 


GCW_STYLE Retrieves the window-class style bits. 


The return value is the 16-bit value in the window’s reserved memory, if the func- 
tion is successful. Otherwise, it is zero, indicating the hwnd or offset parameter is 
invalid. | | | 


To access any extra two-byte values allocated when the window-class structure 
was created, use a positive byte offset as the index specified by the offset parame- 
ter, starting at 0 for the first two-byte value in the extra space, 2 for the next two- 
byte value, and so on. | | 


GetClassInfo, GetClassLong, GetClassName, RegisterClass, SetClassWord 
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GetClientRect [ex | 


void GetClientRect(hwnd, [prc) 
HWND hwnd; /* handle of window */ 
RECT FAR? [prc; /* address of structure for rectangle | 


The GetClientRect function retrieves the client coordinates of a window’s client 
area. The client coordinates specify the upper-left and lower-right corners of the 
client area. Because client coordinates are relative to the upper-left corner of a win- 
dow’s client area, the coordinates of the upper-left corner are (0,0). 


Parameters © hwnd , 
Identifies the window whose client coordinates are to be retrieved. 


lpre | 
Points to a RECT structure that receives the client coordinates. The left and 
top members will be zero. The right and bottom members will contain the 


width and height of the window. The RECT structure has the following form: 


typedef struct tagRECT { /* ro */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


See Also GetWindowRect 


GetClipboardData | i Pax] 
HANDLE GetClipboardData(uFormat) 
UINT uFormat; /* data format */ 


The GetClipboardData function retrieves a handle of the current clipboard data 
having a specified format. The clipboard must have been opened previously. 


338 GetClipboardFormatName 


Parameters 


Return Value | 


Comments 


See Also 


GetClipboardFormatName 


uFormat 
_ Specifies the format of the data accessed by this function. For a description of 
the possible data formats, see the description of the SetClipboardData func- 
tion. 


The return value is a handle of the clipboard data in the specified format, if the 
function is successful. Otherwise, it is NULL. 


The available formats can be enumerated in advance by using the Enum- 
ClipboardFormats function. 


The data handle returned by the GetClipboardData function is controlled by the 
clipboard, not by the application. The application should copy the data immedi- 
ately, instead of relying on the data handle for long-term use. - The application 
should not free the data handle or leave it locked. 


Windows supports two formats for text: CF_TEXT (the default Windows text 
clipboard format) and CF_OEMTEXT (the format Windows uses for text in non- 
Windows applications). If you call GetClipboardData to retrieve data in one text 
format and the other text format is the only available text format, Windows auto- 
matically converts the text to the requested format before supplying it to your ap- 
plication. | 


If the clipboard contains data in the CF_PALETTE (logical color palette) format, 
the application should assume that any other data in the eappowe ! is realized 
against that pele palette. 


CloseClipboard, EnumClipboardFormats, IsClipboardFormatA vailable, 
OpenClipboard, SetClipboardData “3 


int GetClipboardFormatName(uFormat, lpszFormatName, cbMax) 


UINT uFormat; /* format to retrieve = 
LPSTR IpszFormatName; /* address of buffer for name a | 
int chMax; /* length of name string sae 


Parameters 


The GetClipboardFormatName function retrieves the name of a registered clip- 
board format. , 


uF ormat 
Specifies the registered format to retrieve. This parameter must not specify any 
of the predefined ren formats. 


Return Value 


See Also 
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lpszFormatName 
Points to a buffer that receives the format name. 


cbhMax 
Specifies the maximum length, in bytes, of the format-name string. The format- 
name string is truncated if it is longer. — 


_ The return value is the length, in bytes, of the returned format name if the function 


is successful. Otherwise, it is zero, indicating the requested format does not exist 
or is predefined. 


CountClipboardFormats, EnumClipboardFormats, GetPriorityClipboard- 
Format, ne Mpboary norman nvalans piu arias 


GetClipboardOwner ‘ [ 2.x | 


HWND GetClipboardOwner(void) 


Parameters 


Return Value 


Comments 


See Also 


The GetClipboardOwner function retrieves the handle of the window that cur- 
rently owns the clipboard, if any. 


This function has no parameters. 


The return value identifies the window that owns the clipboard if the function is 
successful. Otherwise, it is NULL. . 


The clipboard can still contain data even if the clipboard is not currently owned. 


| CloseClipboard, GetClipboardData, GetClipboard Viewer, OpenClipboard 


GetClipboardViewer [ax] 


HWND GetClipboardViewer(void) 


- Parameters 


The GetClipboard Viewer function retrieves the handle of the first window i in the 
ie ppOane viewer chain. | e% 


_ This function has no parameters. 
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Return Value The return value identifies the window currently responsible for displaying the 
clipboard, if the function is successful. Otherwise, it is NULL (if there is no 
viewer, for example). 


See Also CloseClipboard, GetClipboardData, GetClipboardOwner, OpenClipboard 


GetClipBox Ea 


int GetClipBox(hdc, Iprc) 
HDC hdc; /* handle of device context ab 
RECT FAR®* [prc; /* address of structure with rectangle ay) 


The GetClipBox function retrieves the dimensions of the smallest rectangle that 
completely contains the current clipping region. | 


Parameters hdc 
Identifies the device context. 


[prc | | 
Points to the RECT structure that receives the logical coordinates of the rec- 
tangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int botton; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value The return value is SIMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR. 


See Also GetBoundsRect, GetRgnBox, GetTextExtent, SelectClipRgn 
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GetClipCursor 


void GetClipCursor(/prc) | —— 
RECT FAR® [prc; ‘i address of structure for rectangle */ 


The GetClipCursor function retrieves the screen coordinates of the rectangle to 
which the cursor has been confined by a previous call to the ClipCursor function. 


Parameters Ipre 
Points to a RECT structure that receives the screen coordinates of the confining 
rectangle. The structure receives the dimensions of the screen if the cursor is » 
not confined to a rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; | 
int top; 
int right; 
int bottom; 
} -RECT; 


For a full description of this structure, see the M. icrosoft Windows 8 Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


See Also ClipCursor, GetCursorPos 


GetCodeHandle ete oe 


- HGLOBAL GetCodeHandle(ipProc) 
FARPROC [pProc;. _—/* instance address of function **/ 


The GetCodeHandle function determines which code segment contains the — 
specitied function. 


Parameters Hs IpProc 
7 Points to the procedure-instance address of the fahetion for which to return the 
code segment. Typically, this address i is returned by the MakeProcInstance 
function. | 


Return Value The return value identifies the code segment that contains the function if the Get- 
CodeHandle function is successful. Otherwise, it is NULL. 


342 GetCodelnfo 


Comments If the code segment that contains the function is already loaded, the GetCode- 
Handle function marks the segment as recently used. If the code segment is not 
loaded, GetCodeHandle attempts to load it. Thus, an application can use this func- 
tion to attempt to preload one or more segments necessary to perform a particular 
task. 


See Also MakeProclInstance 
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void GetCodeInfo(/pProc, lpSegInfo) ) 
FARPROC IpProc; /* function address or module handle se 
SEGINFO FAR* [pSegInfo; /* address of structure for segment information si 


The GetCodelInfo function retrieves a pointer to a structure containing informa- 
tion about a code segment. | 


Parameters IpProc 
Specifies the procedure-instance address of the function (typically, returned by 
the MakeProclInstance function) in the segment for which information is to be 
retrieved, or it specifies a module handle (typically, returned by the Get- 
ModuleHandle function) and segment number. 7 


lpSegInfo 
Points to a SEGINFO structure that will be filled with information about the 
code segment. The SEGINFO structure has the following form: 


typedef struct tagSEGINFO { 
UINT offSegment; 
UINT = cbSegment; 
UINT flags; 
UINT cbAlloc; 
HGLOBAL h; 
UINT  alignShift; 
UINT reserved[2]; 

} SEGINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


See Also GetModuleHandle, MakeProcInstance 
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GetCommError 2x | 


int GetCommError(idComDev, lpStat) 
int idComDev; /* communications device identifier 3 
COMSTAT FAR* IpStat; /* address of device-status buffer i 


_ The GetCommError function retrieves the most recent error value and current 
status for the specified device. 


When a communications error occurs, Windows locks the communications port 
until GetCommError clears the error. 


Parameters idComDev | 
Specifies the communications device to be examined. The OpenComm func- 
tion returns this value. 7 


lpStat 
Points to the COMSTAT si structure ee is to receive the device status. If this pa- 
rameter is NULL, the function returns only the error values. The COMSTAT 
structure has the following form: 


typedef struct tagCOMSTAT : /* cmst * / 
BYTE status; ce /* status of ceansinicsioe | kf 
UINT cbInQue; '/* count of characters in Rx Queue */ 
UINT cbOutQue; | - /* count of characters in Tx Queue */ 
— } COMSTAT; oe : : + 


For a full description of this structure, see the Microsoft Windows Program- | 
mer’s Reference, Volume 3. : 


Return Value _ The return vale specifies the error value for the most recent communications- _ 
. - function call to the specified device, if GetCommError is successful. 


Errors The return value ¢ can be a combination of the following values: 
| Value > < Meaning | 
CE_BREAK Hardware detected a break condition. 


CE_CTSTO ~— CTS (clear-to-send) timeout. While a character was being trans- 
3 7 mitted, CTS was low for the duration specified by the f{CtsHold — 
member of the COMSTAT structure. 


CE_DNS 3 Parallel device was not selected. 


_CE_DSRTO ___ DSR (data-set-ready) timeout. While a character was being trans- 
| | - mitted, DSR was low for the duration specified by the fDsrHold 
member of COMSTAT. : 


_CE_FRAME —__ Hardware detected a framing error. 
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See Also 


Value Meaning 

CE_IOE I/O error occurred during an attempt to communicate with a oe 

| lel device. 

CE_MODE Requested mode is not supported, or the idComDev putas is 
invalid. If set, CE_MODE is the only valid error. 

CE_OOP Parallel device signaled that it is out of paper. 


CE_OVERRUN Character was not read from the hardware before the next charac- 
ter arrived. The character was lost. 


CE_PTO Timeout occurred during an attempt to communicate with a paral- 
lel device. 
CE_RLSDTO RLSD (receive-line-signal-detect) timeout. While a character was 


being transmitted, RLSD was low for the duration specified by 
the fRlsdHold member of COMSTAT. 


CE_RXOVER Receiving queue overflowed. There was either no room in the | 
input queue or a character was received after the end-of-file char- 
acter was received. 


CE RXPARITY Hardware detected a parity error. 


CE_TXFULL Transmission queue was full when a function attempted to queue 
a character. 


OpenComm 


GetCommEventMask a ra] 


UINT GetCommEventMask(idComDey, fnEvtClear) 


int idComDev; 
int fnEvtClear; 


Parameters 


Return Value 


/* communications device identifier */ 
/* events to clear in the event word **/ 


The GetCommEventMask function retrieves and then clears the event word for a 
communications device. 


idComDev 
Specifies the communication device to be examined. The OpenComm function 
returns this value. 


jnEvtClear 
Specifies which events are to be cleared in the event word. For a list of the 
event values, see the description of the SetCommEventMask function. 


The return value specifies the current event-word value for the specified com- 
munications device if the function is successful. Each bit in the event word speci- 
fies whether a given event has occurred; a bit is set (to 1) if the event has occurred. 
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Comments Before the GetCommEventMask function can record the occurrence of an event, 
an application must enable the event by using the SetCommEventMask function. 


If the communication device event is a line-status or printer error, the application 
should call the GetCommError function after calling GetCommEventMask. 


See Also GetCommError, OpenComm, SetCommEventMask 


GetCommState | | [x] 


int GetCommState(idComDey, Ipdcb) 


int idComDev; /* communications device identifier */ 
DCB FAR® [pdcb; /* address of structure for device control block i 
The GetCommsState function retrieves the device control block for the specified 
device. 
Parameters - idComDev 
Specifies the device to be examined. The OpenComm function returns this 
value. 
lpdcb 


Points to the DCB structure that is to receive the current device control block. 
The DCB structure defines the control settings for the device. It has the follow- 


ing form: 

typedef struct tagDCB /* dcb | a / 

{ | : 
BYTE Id; /* internal device identifier */ 
UINT BaudRate; /* baud rate ft 
BYTE ByteSize; /* number of bits/byte, 4-8 * / 
BYTE Parity; /* Q@-4=none,odd,even,mark,space */ 
BYTE StopBits; | ~ /e 01,2 = 1, 1.5, 2 © * / 
UINT RisTimeout; /* timeout for RLSD to be set * / 
UINT CtsTimeout; /* timeout for CTS to be set * / 
UINT DsrTimeout; /* timeout for DSR to be set * / 


/* binary mode (skip EOF check) — */ 
/* don't assert RTS at init time * / 


UINT fBinary 
UINT fRtsDisable 


UINT fParity /* enable parity checking Rf 
—UINT fOutxCtsFlow CTS handshaking on output kL 
UINT fOutxDsrFlow /* DSR panidsfak ing: on output _ ef 
UINT fDummy /* reserved : —e/ 


ee ee ee oe ee ee ee 
oa a Se oe 
we =e we we we we we 
~~ 
* 


UINT fDtrDisable /* don't assert DTR at init time */— 
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UINT fOutx tl;  /* enable output XON/XOFF * / 
UINT fInXx :1;  /* enable input XON/XOFF * / 
UINT fPeChar :1;  /* enable parity err replacement — */ 
UINT fNull. :1;  /* enable null stripping * / 
UINT fChEvt :1; /* enable Rx character event * / 
UINT fDtrflow :1;  /* DTR handshake on input * / 
UINT fRtsflow :1;  /* RTS handshake on input * / 
UINT fDummy2 ¢1; 

char XonChar; /* Tx and Rx XON character * / 
char XoffChar; | /* Tx and Rx XOFF character * / 
UINT XonLim; /* transmit XON threshold * / 
UINT XoffLim; /* transmit XOFF threshold * / 
char PeChar; /* parity error replacement char ¥*/ 
char EofChar; /* end of Input character * / 
char EvtChar; /* received event character a / 
UINT TxDelay; /* amount of time between chars * / 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value — The return value is zero if the function is successful. Otherwise, it is less than zero. 


See Also | OpenComm, SetCommState 


GetCurrentPDB 


UINT GetCurrentPDB(void) 


The GetCurrentPDB function returns the selector address of the current 
MS-DOS program database (PDB), also known as the program segment prefix 


(PSP). 
Parameters 7 This fieon has no parameters. 
Return Value The return value is the selector address of the current PDB if the function is 
successful. | 
ciampla The following example uses the GetCurrentPDB function to list the current com- 


mand tail: 
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typedef struct { 


WORD pspInt2Q@; /* Int 20h instruction * / 
WORD pspNextParagraph; /* segment addr. of next paragraph */ 
BYTE resl; /* reserved * / 
BYTE pspDispatcher[5];. /* long call to MS-DOS | * / 
DWORD pspTerminateVector; /* termination address (Int 22h) a / 
DWORD pspControlCVector; /* addr of CTRL+C (Int 23h) a / 
DWORD pspCritErrorVector; /* addr of Crit-Error (Int 24h) * / 
WORD res2[11]; /* reserved * / 
WORD pspEnvironment; /* segment address of environment */ 
WORD res3[23]; /* reserved a / 
BYTE pspFCB_1[16]; /* default FCB #1 * / 
BYTE pspFCB_2[16]; /* default FCB #2 * / 
DWORD res4; /* reserved * / 


BYTE pspCommandTail[128]; /* command tail (also default DIA) */ 
} PSP, FAR* LPSP; 


LPSP Ipsp = (LPSP) MAKELP(GetCurrentPDB(), @); 


MessageBox(NULL, 1lpsp->pspCommandTail, "PDB Command Tail™, MB_OK); 


GetCurrentPosition aor Ea 
DWORD GetCurrentPosition(hdc) | 
HDC hdc; /* handle of device context a 


The GetCurrentPosition function retrieves the logical coordinates of the current 
position. The current position is set by using the MoveTo function. 


Parameters hdc 
Identifies the device context. 


Return Value The low-order word of the return value contains the logical x-coordinate of the cur- 
rent position if the function is successful; the high-order word contains the logical 
y-coordinate. 7 - 


— See Also LineTo, MoveTo 
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GetCurrentPositionEx 8 [ 3.1 | 


BOOL GetCurrentPositionEx(hdc, lpPoint) 


HDC hdc; 
POINT FAR® [pPoint; 
The GetCurrentPositionEx function retrieves the current position in logical 
coordinates. 
Parameters hdc 
Identifies the device context to get the current position from. 
lpPoint 
Points to a POINT structure that gets filled with the current position. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. _ 


GetCurrentTask ax 


HTASK GetCurrentTask(void) 


The GetCurrentTask function retrieves the handle of the current (running) task. 
Parameters _. This function has no parameters. 


Return Value The return value is a handle of the current task if ite function is successful. Other- 
wise, itis NULL. 


GetCurrentTime — “Fe ks a [2x] 
DWORD GetCurrentTime(void) | | 


The GetCurrentTime function retrieves the number of milliseconds that have 
elapsed since Windows was started. 


Parameters | This function has no parameters. 
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Return Value The return value is the number of milliseconds that have elapsed since Windows 
was Started, if the function was successful. 


Comments The GetCurrentTime function is identical to the GetTickCount function. Appli- 
cations should use the GetTickCount function, since its name matches more 
closely with what the function does. 


See Also GetTickCount 


GetCursor | EXE 


HCURSOR GetCursor(void) 


The GetCursor function retrieves the handle of the current cursor. 


Parameters - This function has no parameters. 

Return Value The return value is the handle of the current cursor if a cursor exists. Otherwise, it 
is NULL. 

See Also SetCursor 


GetCursorPos Tae od [ 2x | 


void GetCursorPos(/ppt) 


POINT FAR® Ippt; /* address of structure for cursor position */ 
The GetCursorPos function retrieves the screen coordinates of the cursor’s cur- 
rent position. | | 
Parameters [ppt 


Points to the POINT structure that receives the cursor position, in screen 
coordinates. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; : 
int y; 

} POINT; 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


Comments The cursor position is always given in screen coordinates and is not affected by 
the mapping mode of the window that contains the cursor. 


See Also | ClipCursor, SetCursorPos 


GetDC [2x | 


HDC GetDC(hwnd) 
HWND hwnd; /* handle of window */ 


The GetDC function retrieves the handle of a device context for the client area of 
the given window. The device context can be used in subsequent graphics device 
interface (GDI) functions to draw in the client area. 


The GetDC function retrieves a common, class, or private device context, depend- 
ing on the class style specified for the given window. For common device con-. 
texts, GetDC assigns default attributes to the context each time it is retrieved. For 
class and private contexts, GetDC leaves the previously assigned attributes un- 
changed. 


Parameters hwnd 
Identifies the window where drawing will occur. If this parameter is NULL, the 
function returns a device context for the screen. 


Return Value The return value is a handle of the device context for the given window’s client 
, area, if the function is successful. Otherwise, it is NULL. 


Comments Unless the device context belongs to a window class, the ReleaseDC function 
must be called to release the context after drawing. Since only five common 
device contexts are available at any given time, failure to release a device context 
can prevent other applications from accessing a device context. If the hwnd pa- 
rameter of the GetDC function is NULL, the first parameter of ReleaseDC should 

~ also be NULL. 


A device context belonging to the window’s class is returned by the GetDC func- 
tion if CS_CLASSDC, CS_OWNDC, or CS_PARENTDC style was specified in 
the WNDCLASS structure when the class was registered. 


See Also 


GetDCEx 
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BeginPaint, GetWindowDC, ReleaseDC 


HDC GetDCEx(hwnd, hrgnClip, fdwOptions) 


register HWND hwnd; 


HRGN hrgnClip; 


/* window where drawing will occur **/ 


/* clipping region that may be combined =] 


DWORD fdwOptions; /* device-context options 


Parameters 


a, 


The GetDCEx function retrieves the handle of a device context for the given win- 
dow. The device context can be used in subsequent graphics device interface 
(GDI) functions to draw in the client area. 


This function, which is an extension to the GetDC function, gives an application 
more control over how and whether a device context for a window is clipped. 


hwnd 


Identifies the window where drawing will occur. 


hrgnClip 


Identifies a dipping region that may be combined with the visible region of the 


client window. 
fdwOptions 


Specifies how the device context is created. This parameter can be a combina- 


tion of the following values: 
Value 


DCX CACHE 


DCX_CLIPCHILDREN 
DCX_CLIPSIBLINGS 
DCX EXCLUDERGN 


DCX_INTERSECTRGN 


Meaning | 


Returns a device context from the cache, 
rather than the OWNDC or CLASSDC win- 
dow. Essentially overrides CS_OWNDC and 
CS_CLASSDC. 


Excludes the visible regions of all child win- 
dows below the window identified by the 
hwnd parameter. 

Excludes the visible regions of all sibling win- 
dows above the window identified y the 
hwnd parameter. 

Excludes the clipping region identified by the 
hrgnClip parameter from the visible region of 
the returned device context. 


Intersects the clipping region identified by 


— the hrgnClip parameter with the visible re- 


gion of the returned device context. . 
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Value , Meaning 


DCX_LOCKWINDOWUPDATE Allows drawing even if there is a Lock- 
WindowUpdate call in effect that would 
otherwise exclude this window. This value is 
used for drawing during tracking. 


DCX_PARENTCLIP Uses the visible region of the parent 
window, ignoring the parent window’s 
WS_CLIPCHILDREN and WS_PARENTDC 
style bits. This value sets the device context’s 
origin to the upper-left corner of the window 
identified by the hwnd parameter. 


DCX_WINDOW | Returns a device context corresponding to 
the window rectangle rather than the client 
rectangle. 
Return Value The return value is a handle of the device context for the specified window, if the 


function is successful. Otherwise, it is NULL. 


Comments Unless the device context belongs to a window class, the ReleaseDC function 
| must be called to release the context after drawing. Since only five common 
device contexts are available at any given time, failure to release a device context 
can prevent other applications from accessing a device context. 


A device context belonging to the window’s class is returned by the GetDCEx 
function if the CS_CLASSDC, CS_OWNDC, or CS_PARENTDC class style was 
specified in the WNDCLASS structure when the class was registered. 


In order to obtain a cached device context, an application must specify 
DCX_CACHE. If DCX_CACHE is not specified and the window is neither 
CS_OWNDC nor CS_CLASSDC, this function returns NULL. 


See Also ; BeginPaint, GetDC, GetWindowDC, ReleaseDC 


GetDCOm ts [a 


DWORD GetDCOrg(hdc) | 
HDC hdc; _—— /* handle of device context  */ 


_The GetDCOrg function retrieves the coordinates of the final translation origin 
for the device context. This origin specifies the offset used by Windows to trans- 
late device coordinates into client coordinates for points in an application’s win- 
dow. The final translation origin is relative to the physical origin of the screen. © 


Parameters 


Return Value 


Example 


See Also 
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hdc 
Identifies the device context whose origin is to be retrieved. 


The low-order word of the return value contains the x-coordinate of the final trans- 
lation origin, in device coordinates, if the function is successful; the high-order 
word contains the y-coordinate. 


The following example uses the CreateIC function to create an information con- 
text for the screen and then retrieves the context’s origin by using the GetDCOrg 
function: , 


HDC hdcIC; 
DWORD dwOrigin; 


hdcIC = CreateIC("DISPLAY", NULL, NULL, NULL); 
dwOrigin = GetDCOrg(hdcIC); 


~DeleteDC(hdcIC); 


CreateIC 


GetDesktopWindow PR i, 


HWND GetDesktop Window(void) 


Parameters 
Return Value 


See Also 


The GetDesktop Window function retrieves the handle of the desktop window. 
The desktop window covers the entire screen and is the area on top of which all 
icons and other windows are painted. 


This function has no parameters. 
The return value is a handle of the desktop window. 


GetTop Window, GetWindow 
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GetDeviceCaps —e ry 


int GetDeviceCaps(hdc, iCapability) 
HDC hdc; _ /* handle of device context i 
int iCapability; —_/* index of capability to query i 


The GetDeviceCaps function retrieves device- -specific information about a given 
onbey device. 


Parameters hdc 
Identifies the device context. 
iCapability 
Specifies the type of information to be returned. It can be one of the following 


indices: 


Index 


DRIVERVERSION 


TECHNOLOGY 


HORZSIZE 
VERTSIZE 
HORZRES 
VERTRES 
LOGPIXELSX 
LOGPIXELSY 
BITSPIXEL 
PLANES 


_ NUMBRUSHES 


NUMPENS 
NUMMARKERS 
NUMFONTS 


-NUMCOLORS 


Description 


Version number of the device driver. 
Device technology. It can be one of the following values: 


Value — | _ Meaning 

DT_PLOTTER | Vector plotter 
DT_RASDISPLAY Raster display 
DT_RASPRINTER Raster printer 
DT_RASCAMERA Raster camera 


DT_CHARSTREAM Character stream 
DT_METAFILE Metafile 


DT_DISPFILE Display file 


Width of the physical display, in millimeters. 

Height of the physical display, in millimeters. 

Width of the display, in pixels. 

Height of the display, in raster lines. 7 
Number of pixels per logical inch along the ‘isi width. 
Number of pixels per logical inch along the display height. | 
Number of adjacent color bits for each pixel. 
Number of color planes. 

Number of device-specific brushes. 

Number of device-specific pens. 


Number of device-specific markers. 


Number of device-specific fonts. 
Number of entries in the device’s color table. 


Index 


ASPECTX 
ASPECTY 
ASPECTXY 
PDEVICESIZE 
CLIPCAPS 


STIZEPALETTE 


NUMRESERVED 


COLORRES ~ 


- RASTERCAPS 
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Description 


Relative width of a device pixel used for line drawing. 
Relative height of a device pixel used for line drawing. 
Diagonal width of a device pixel used for line drawing. 
Size of the PDEVICE internal structure, in bytes. 
Clipping capabilities the device supports. It can be one of 


the following values: 
Value Meaning 


CP_NONE | Output is not clipped. 
CP_RECTANGLE Output is clipped to rectangles. 


~ CP_REGION Output is clipped to regions. 


Number of entries in the system palette. This index is 
valid only if the device driver sets the RC_PALETTE bit 
in the RASTERCAPS index; it is available only if the 


driver is written for Windows 3.0 or later. 


_ Number of reserved entries in the system palette. 
_ This index is valid only if the device driver sets the 
~RC_PALETTE bit in the RASTERCAPS index; it is avail- 
able only if the driver is written for Windows 3.0 or later. 
~ Color resolution of the device, in bits per pixel. This index — 
is valid only if the device driver sets the RC_PALETTE 
bit in the RASTERCAPS index; it is available only if the 
_. driver is written for Windows 3.0 or later. | 


Raster capabilities the device supports. It can be a combi-- 
nation of the following values: ) 


- Value Meaning 
RC_BANDING _ Supports banding. | 
RC_BIGFONT Supports fonts larger than 
64K. | 

RC_BITBLT - Transfers bitmaps. 
RC_BITMAP64 Supports bitmaps larger than 

3 : 64K. : 
RC_DEVBITS Supports device bitmaps. 
RC_DI_BITMAP Supports the SetDIBits and 

| GetDIBits functions. 
-RC_DIBTODEV Supports the SetDIBitsTo- 


Device function. | 


-RC_FLOODFILL —_ Performs flood fills. 


RC_GDI20_OUTPUT _ Supports Windows version 
2.0 features. — 
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Index Description 


Value Meaning 
RC_GDI20_STATE Includes a state block in the 
_ device context. 
RC_NONE Supports no raster operations. 
RC_OP_DX_OUTPUT Supports dev opaque and DX 
array. 
RC_PALETTE Specifies a palette-based 
device. 
RC_SAVEBITMAP Saves bitmaps locally. 
RC_SCALING Supports scaling. 
RC_STRETCHBLT Supports the StretchBlt func- 
tion. | 
RC_STRETCHDIB Supports the StretchDIBits 
function. 
CURVECAPS Curve capabilities the device supports. It can be a combi- 
nation of the following values: 
Value Meaning 
CC_NONE Supports curves. 
CC_CIRCLES Supports circles. 
CC_PIE Supports pie wedges. 
CC_CHORD Supports chords. 
CC_ELLIPSES Supports ellipses. 
CC_WIDE Supports wide borders. 
CC_STYLED Supports styled borders. 
CC_WIDESTYLED Supports wide, styled borders. 
CC_INTERIORS Supports interiors. 


CC_ROUNDRECT Supports rectangles with 
rounded corners. 


LINECAPS Line capabilities the device supports. It can be a combina- 


tion of the following values: 

Value Meaning 
LC_NONE Supports no lines. 
LC_POLYLINE Supports polylines. 
LC_MARKER Supports markers. 


LC_POLYMARKER Supports polymarkers. 


Index 


POLY GONALCAPS 


, TEXTCAPS 


_ Description 


Value 


-LC_WIDE 


LC_STYLED 
LC_WIDESTYLED 
LC_INTERIORS 
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Meaning 


Supports wide lines. 
Supports styled lines. 
Supports wide, styled lines. 
Supports interiors. 


Polygonal capabilities the device supports. It can be a 
combination of the following values: 


Value 


PC_NONE 
PC_POLYGON 


PC_RECTANGLE 
PC_WINDPOLYGON 


PC_SCANLINE 


-PC_WIDE 


PC_STYLED 
PC_WIDESTYLED 
PC_INTERIORS 


Meaning 
Supports no polygons. 


Supports alternate fill poly- 
gons. 


Supports rectangles. 


Supports winding number fill 
polygons. » 


Supports scan lines. 

Supports wide borders. 

Supports styled borders. 

Supports wide, styled borders. 
Supports interiors. - 


Text capabilities the device supports. It can be a combina- 


tion of the following values: 


Value 


TC_OP_CHARACTER 


TC_OP_ STROKE 


- TC_CP STROKE 


Meaning 


' Supports character output pre- 


cision, which indicates the 
device can place device fonts 
at any pixel location. This is 
required for any device with 
device fonts. 


| Supports stroke output preci- 


sion, which indicates the : a 
device can omit any stroke of 
a device font. pepe tes 4 
Supports stroke clip preci-— 


sion, which indicates the 


device can clip device fonts 
to a pixel boundary. | 
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Index 


Description 


Value 


TC_CR_90 


TC_CR_ANY 


TC_SF_X_YINDEP 


TC_SA_DOUBLE 


TC_SA_INTEGER 


TC_SA_CONTIN 


TC_EA_DOUBLE 


TC_IA_ABLE 


Meaning 


Supports 90-degree character 
rotation, which indicates the 
device can rotate characters 
only 90 degrees at a time. 


Supports character rotation at 
any degree, which indicates 
the device can rotate device 
fonts through any angle. 


Supports scaling independent 
of x and y directions, which 
indicates the device can scale 
device fonts separately in x 
and y directions. 


Supports doubled characters 
for scaling, which indicates 
the device can double the 
size of device fonts. 


Supports integer multiples — 
for scaling, which indicates 
the device can scale the size 
of device fonts in any integer 
multiple. 


Supports any multiples for 
exact scaling, which indicates 
the device can scale device 
fonts by any amount but still 
preserve the x and y ratios. 


Supports double-weight char- 
acters, which indicates the 
device can make device fonts 
bold. If this bit is not set for 
printer drivers, graphics 
device interface (GDI) at- 
tempts to create bold device 
fonts by printing them twice. 


Supports italics, which indi- 
cates the device can make 
device fonts italic. If this bit 
is not set, GDI assumes 
italics are not available. 
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Index Description 
Value Meaning 
TC_UA_ABLE Supports underlining, which 


indicates the device can un- 
derline device fonts. If this 
bit is not set, GDI creates un- 
derlines for device fonts. 


TC_SO_ABLE Supports strikeouts, which in- 
-dicates the device can 
strikeout device fonts. If this 
bit is not set, GDI creates 
strikeouts for device fonts. 


TC_RA_ ABLE Supports raster fonts, which 
. indicates that GDI should 

enumerate any raster or True- 
Type fonts available for this 
device in response to a call to 
the EnumFonts or Enum- 
FontFamilies function. If 
this bit is not set, GDI- | 
supplied raster or TrueType 
fonts are not enumerated 
when these functions are 
called. 


TC_VA_ABLE | Supports vector fonts, which 
indicates that GDI should 
enumerate any vector fonts 
available for this device in 
response to a call to the 
EnumFonts or EnumFont- - 
Families function. This is sig- 
nificant for vector devices . 
only (that is, for plotters). 

Display drivers (which must 
be able to use raster fonts) 
and raster printer drivers al- 
ways enumerate vector fonts, _ 
because GDI rasterizes vector 

_ fonts before sending them to 
the driver. poe 


TC_RESERVED ep - Reserved; must be zero. 
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Return Value — The return value is the value of the requested capability if the function is 
successful. | 
Example The following example uses the GetDeviceCaps function to determine whether a 


device supports raster capabilities and is palette-based. If so, the example calls the 
GetSystemPaletteUse function. 


WORD nUse; 


hdc = GetDCC(hwnd); 

if ((GetDeviceCaps(hdc, RASTERCAPS) & RC_PALETTE) == @) { 
ReleaseDC(hwnd, hdc); 
break; 

} 

nUse = GetSystemPaletteUse(hdc) ; 

ReleaseDC(hwnd, hdc); 


GetDialogBaseUnits 


DWORD GetDialogBaseUnits(void) 


The GetDialogBaseUnits function returns the dialog box base units used by Win- 
dows when creating dialog boxes. An application should use these values to calcu- 
late the average width of characters in the system font. 


Parameters This function has no parameters. 


Return Value The low-order word of the return value contains the width, in pixels, of the current 
7 dialog box base-width unit, if the function is successful (this base unitis derived | 
from the system font); the high-order word of the return value contains the height, 
in pixels. | 


Comments The values returned represent dialog box base units before being scaled to dialog 
box units. The dialog box unit in the x-direction is one-fourth of the width 
returned by the GetDialogBaseUnits function. The dialog box unit in the 

- y-direction is one-eighth of the height returned by the function. 


To use GetDialogBaseUnits to determine the height and width, in pixels, of a con- 
trol, given the width (x) and height (y) in dialog box units and the return value 
(IDlgBaseUnits), use the following formulas: 


(x * LOWORD(1DIgBaseUnits)) / 4 - 
(Cy * HIWORD(1DIigBaseUnits)) / 8 


Example 
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To avoid rounding problems, perform the multiplication before the division, in 
case the dialog box base units are not evenly divisible by four. 


The following example calculates tab stops based on the dialog box base units: 


HMENU hmenu; 
WORD DigWidthUnits; 
WORD TabStopList[4]; 


case WM_CREATE: 
hmenu = LoadMenu(hinst, “TabStopsMenu"); 
SetMenu(hwnd, hmenu); 
DigWidthUnits = LOWORD(GetDialogBaseUnits()) / 4; 


TabStopList[@] = (DlgWidthUnits * 16 * 2); 
—TabStopList[1] = (DlgWidthUnits * 32 * 2); 
TabStopList[2] = (DigWidthUnits * 58 * 2); 
- TabStopList[3] = (DlgWidthUnits * 84 * 2); 
break; | | 


int GetDIBits(hdc, i) nStartScan, cScanLines, lpvBits, Ipbmi, fuColorUse) 


HDC hdc; /* handle of device context oe ega h 
HBITMAP hbmp; /*handle of bitmap 3 =|, 
UINT nStartScan; | /* first scan line to set in destination bitmap rs 
UINT cScanLines; _ /* number of scan lines to copy tee 
void FAR* [pvBits; /* address of array for bitmap bits : abe 
BITMAPINFO FAR* Ipbmi; ‘/* address of structure with bitmap data “a a 
/* type of color table | Se 


UINT fuColorUse; 


Parameters 


The GetDIBits function retrieves the bits of the specified bitmap and copies them, 
in device-independent format, into the buffer pointed to by the /pvBits parameter. 


_ The /pbmi parameter retrieves the color format for the device-independent bits. 


hdc 
_ Identifies the device context. 


hbmp 
Identifies the bitmap. 


nStartScan | 
Specifies the first scan line to be set in the bitmap received in the lpvBits pa- 
rameter. | ren 


-cScanLines 


Specifies the number of lines to be copied. 
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Return Value 


Comments 


See Also 


[pvBits | 
Points to a buffer that will receive the pianap bits in device-independent format. 


[pbmi 
Points to a BITMAPINFO structure that specifies the color format and dimen- 
sion for the device-independent bitmap. The BITMAPINFO structure has the 
following form: 


typedef struct tagBITMAPINFO { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 

} BITMAPINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


daar etre 
Specifies whether the bmiColors members of the BITMAPINEO structure are 


to contain explicit RGB values or indices into the currently realized logical 
palette. The fuColorUse parameter must be one of the following values: 


Value Meaning 
DIB_PAL_COLORS Color table is to consist of an array of 16-bit indices into | 

| the currently realized logical palette. 
DIB_RGB_COLORS Color table is to contain literal RGB values. 


The return value specifies the number of scan lines copied from the bitmap if the 
function is successful. Otherwise, it is zero. 


If the /pvBits parameter is NULL, the GetDIBits function fills in the BIT- 
MAPINFO structure to which the /pbmi parameter points but does not retrieve 
bits from the bitmap. 


The bitmap identified by the hbmp parameter must not be selected into a device 


context when the application calls this function. 
The origin for device-independent bitmaps (DIBs) is the lower-left corner of the 


bitmap, not the upper-left corner, which is the origin when the mapping mode is 
ven _TEXT. 
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int GetDilgCtrlID(hwnda) 
HWND hwnd; /* handle of child window */ 


The GetDigCtrlID function returns a handle of a child window. 


Parameters hwnd 
Identifies the child window. 


Return Value The return value is a handle of the child window if the function is successful. 
Otherwise, it is NULL. 


Comments This function returns a handle of any child window, not just that of a control in a 
dialog box. | 


Since top-level windows do not have an identifier, the GetDIlgCtrlID function’s 
return value is invalid if the hwnd parameter identifies a top-level window. 


See Also GetDigItem, GetDigItemInt, GetDigItemText 


GetDigttem se’ ta 


HWND GetDigItem(hwndDlg, idControl) 
HWND hwnaDig; /* handle of dialog box **/ 
int idControl; /* identifier of control a 


The GetDigItem function retrieves the handle of a control that is in the given 
dialog box. 


Parameters hwndDlg 
: Identifies the dialog box that contains the control. 


idControl 
Specifies the identifier of the control to be retrieved. 


Return Value The return value is the handle of the given control if the function is successful. 
| Otherwise, it is NULL, indicating either an invalid dialog HOx handle or a nonex- 
—istent control. | 
Comments The GetDigItem function can be used with any parent-child window pair, not just 


dialog boxes. As long as the hwndDig parameter identifies a parent window and 
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the child window has a unique identifier (as specified by the hmenu parameter in 
the CreateWindow function that created the child window), GetDlgItem returns 
the handle of the child window. 


See Also CreateWindow, GetDigCtrlID, GetDlgItemInt, GetDigItemText, GetWindow 


GetDigltemint | [2x] 


UINT GetDligItemInt(hwndDlg, idControl, lpfTranslated, fSigned) 


HWND hwndDig; /* handle of dialog box es 
int idControl; _ /* identifier of control of 
BOOL FAR® [pfTranslated; /* address of variable for error flag ay | 
BOOL /Signed; / * signed or unsigned indicator */ 


The GetDigItemInt function translates the text of a control in the piven dialog 
box into an integer value. : 


Parameters hwndDig 
Identifies the dialog box. 


idControl | 
Specifies the identifier of the dialog box control to be translated. 


lpfTranslated 
Points to the Boolean variable that is to receive the translated flag. 


Signed 
Specifies whether the value to be retrieved is signed. 


Return Value The return value specifies the translated value of the dialog box item text if the 
function is successful. Since zero is a valid return value, the [pfTranslated parame- 
ter must be used to detect errors. If an application requires a signed return value, it 
should cast the return value as an int type. | 


Comments The function retrieves the text of the given control by sending the control a 
WM_GETTEXT message. The function then translates the text by stripping any 
extra spaces at the beginning of the text and converting decimal digits. The func- 
tion stops translating when it reaches the end of the text or encounters a non- 
numeric character. If the {Signed parameter is TRUE, the GetDlgItemInt function 
checks for a minus sign (—) at the beginning of the text and translates the text into 
a signed number. Otherwise, it creates an unsigned value. 


GetDlgItemInt returns zero if the translated number is greater than 32,767 (for ee 
signed numbers) or 65,535 (for unsigned numbers). When a error occurs, such as 


See Also 
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encountering nonnumeric characters and exceeding the given maximum, Get- 
DigItemInt copies zero to the location pointed to by the /pfTranslated parameter. 
If there are no errors, /pfTranslated receives a nonzero value. If [pfTranslated is 
NULL, GetDlgItemInt does not warn about errors. 


GetDigCtrlID, GetDlgItem, GetDlgItemText 


GetDigitemText a ax] 


int GetDigItemText(hwndD/g, idControl, Ipsz, cbMax) 


HWND hwnadDig; 


int idControl; 
~ LPSTR Ipsz; 
int cbMax; 


Parameters 


Return Value 


Comments : 


See Also 


/* handle of dialog box sf | 
/* identifier of control */ 
/* address of buffer for text */ 
/* maximum size of string +] 


The GetDigItemText function retrieves the title or text associated with a control 
in a dialog box. . 


hwndDlg 
Identifies the dialog box that contains the control. 


idControl | a 

_ Specifies the identifier of the control whose title is to be retrieved. 
lpsz ca. 
Points to a buffer that is to receive the control’s title or text. 
cbMax . 


Specifies the maximum length, in bytes, of the string to be copied to the buffer 
pointed to by the /psz parameter. The string is truncated if it is longer. — 


The return value specifies the number of bytes copied to the buffer, not including 
the terminating null character, if the function is successful. Otherwise, it is zero. 


The GetDlgItemText function sends a WM_GETTEXT message to the control. — 


GetDigCtrlID, GetDigItem, GetDigItemInt 
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GetDOSEnvironment 7 e 


LPSTR GetDOSEnvironment(void) _ 


The GetDOSEnvironment function returns a far pointer to the environment string 
of the current (running) task. 


Parameters This function has no parameters. 

Return Value _ The return value is a far pointer to the current environment string. 

Comments | Unlike an application, a dynamic-link library (DLL) does not have a copy of the 
environment string. As a result, the library must call this function to retrieve the 
environment string. | 7 

Example The following example uses the GetDOSEnvironment function to return a 


pointer to the environment, and then lists the environment settings: 


LPSTR IpszEnv; 


lpszEnv = GetDOSEnvironment(); 
while (*lpszEnv != '\@') { 


. /* process the environment string */ 


/* Move to the next environment string */ | 


IpszEnv += Istrlen(IpszEnv) + 1; 


GetDoubleClickTime fax] 
UINT GetDoubleClickTime(void) 
| The GetDoubleClickTime function retrieves the current double-click time for the 
mouse. A double-click is a series of two clicks of the mouse button, the second oc- 
curring within a specified time after the first. The double-click time is the maxi- 


mum number of milliseconds that may occur between the first and second click of 
a double-click. 


Parameters This function has no parameters. 
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Return Value The return value specifies the current double-click time, in milliseconds. 


See Also GetCapture 


GetDriverinfo [ 3.1 | 


BOOL GetDriverInfo(hdrvr, [pdis) 
HDRVR hdrvr; /* handle of installable driver = */ 


DRIVERINFOSTRUCT FAR* Ipdis; /* address of structure for info a 


The GetDriverInfo function retrieves information about an installable driver. 


Parameters hdrvr | 
Identifies the installable driver. This handle must be retrieved by the Open- 


Driver function. 


lpdis 
Points to a DRIVERINFOSTRUCT structure that receives the aves informa- 


tion. The DRIVERINFOSTRUCT structure has the following form: 


typedef struct tagDRIVERINFOSTRUCT { /* drvinfst */ 
UINT length; 
HDRVR hDriver; 
~ HINSTANCE hModule; 
char szAliasName[128]; 
} DRIVERINFOSTRUCT ; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


GetDriverModuleHandle [aa] 
HINSTANCE GetDriverModuleHandle(hdrvr) | 
HDRVRhdrvr; Ss /* handle of installable driver Bae | 


The GetDriverModuleHandle function retrieves Be instance Hanae ofa module 
that contains an installable driver. 
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Parameters hdrvr 


Identifies the installable driver. This parameter must be retrieved by the Open- 
Driver function. | : 
Return Value The return value is an instance handle of the driver module if the function is 


successful. Otherwise, it is NULL. 


See Also OpenDriver 


GetDriveType © _ 


UINT GetDriveType(DriveNumber) 


int DriveNumber; /*Q =A, 1=B, and so on 7 A 
The GetDriveType function determines whether a disk drive is removable, fixed, 
or remote. 

Parameters DriveNumber 


Specifies the drive for which the type is to be determined (0 = drive A, 
1 = drive B, 2 = drive C, and so on). 


Return Value The return value is DRIVE_REMOVABLE (disk can be removed from the drive), 
| DRIVE_FIXED (disk cannot be removed from the drive), or DRIVE_REMOTE 
(drive is a remote, or network, drive), if the function is successful. Otherwise, the 
return value is zero. 


Example The following example uses the GetDriveType function to determine the drive 
type for all possible disk drives (letters A through Z): 
int iDrive; 
WORD wReturn; 
char szMsg[8@]; 


for (iDrive = @, wReturn = @; 
(iDrive < 26) && (wReturn != 1); iDrive++) { 


wReturn = GetDriveType(iDrive); 


sprintf(szMsg, "drive %c: ", iDrive + 'A'); 
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Switch (wReturn) { 
case @: 


strcat(szMsg, “undetermined"); 
break; 


case DRIVE_REMOVABLE: 
strcat(szMsg, "“removable"); 
break; 


case DRIVE_FIXED: 
strcat(szMsg, “fixed"); 
break; 


case DRIVE_REMOTE: 


strcat(szMsg, "remote (network)"); 
break; 
} 


TextOut(hdc, 10, 15 * iDrive, szMsg, strlen(szMsg)); 


GetExpandedName _ aa 
#include <Izexpand.h> 


int GetExpandedName(/pszSource, lpszBuffer) 
LPCSTR [pszSource; /* specifies name of compressed file © il 
LPSTR IpszBuffer; /* points to buffer receiving original filename */ 


The GetExpandedName function retrieves the original name of a compressed file 


if the file was compressed with the COMPRESS.EXE utility and the /r option was 
specified. 


Parameters IpszSource | 
Points to a string that specifies the name of a compressed file. — 
lpszBuffer 
Points to a buffer that receives the name of the compressed file. 


Return Value The return value is TRUE if the function is successful. Otherwise, it is an error 


value that is less than zero, and it may be LZERROR_BADINHANDLE, which 
means that the handle identifying the source file was not valid. 
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Example 


GetExpandedName 


The following example uses the GetExpandedName function to retrieve the origi- 
nal filename of a compressed file: 


char szSrc[] = {"readme.cmp"}; 

char szFileName[128]; 

OFSTRUCT ofStrSrc; | 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile, hfCompFile; 
int cbRead; 

BYTE abBuf[512]; 


/* Open the compressed source file. */ 
hfSrcFile = OpenFile(szSrc, &ofStrSrc, OF_READ); 
/* 
* Initialize internal data structures for the decompression 
* operation. 
* / 
hfCompFile = LZInit(hfSrcFile); 
/* Retrieve the original name for the compressed file. */ 
GetExpandedName(szSrc, szFileName); 
/* Create the destination file using the original name. */ 
hfDstFile = LZOpenFile(szFileName, &ofStrDest, OF_CREATE); 
/* Copy the compressed source file to the destination file. */ 
do { 
if ((cbRead = LZRead(hfCompFile, abBuf, sizeof(abBuf))) > @) 
_Iwrite(hfDstFile, abBuf, cbRead); 
else { 


. /* handle error condition */ 


} 
} while (cbRead == sizeof(abBuf)); 


/* Close the files. */ 


-LZClose(hfSrcFile); 
 LZClose(hfDstFile); 
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Comments This function retrieves the original filename from the header of the compressed 
file. If the source file is not compressed, the filename to which /pszSource points 
is copied to the buffer to which /pszBuffer points. 


If the /r option was not set when the file was compe: the string in the buffer 
to which IpszBuffer points is invalid. 


GetFileResource > [aa] 
#include <ver.h> 


BOOL GetFileResource(/pszFileName, IpszResType, IpszResID, dwF lof, dwResLen, [pvData) 
-LPCSTR I[pszFileName; /* address of buffer for filename 


LPCSTR IpszResType; /* address of buffer for resource type i 
LPCSTR IpszResID; /* address of buffer for resource ID +f. 
~DWORD dwFileOffset; /* resource offset in file we 
DWORD dwResLen; /* size of resource buffer ee ene 
void FAR* IpvData;_ —s/* address of buffer for resource copy | 


The GetFileResource function copies the specified resource from the specified 
file into the specified buffer. To obtain the appropriate buffer size, the application 
can call the GetFileResourceSize function before calling GetFileResource. 


Parameters IpszFileName — 
Points to the buffer that « contains the name of the file containing the 1 resource. 


lpszResType 
Points to a value that is created by using the MAKEINTRESOURCE macro 
with the numbered resource type. This value is pica Vs. _FILE NEO, 


IpszResID 
Points to a value that is created by using the MAKEINTRESOURCE | 
macro with the numbered resource identifier. This value 1 is typically 
~ VS_VERSION_ INFO. 


dwFileOffset | 
Specifies the offset of the resource within the file. ‘The GetFileResourceSize 
function returns this value. If this pe is NULL, the GetFileResource 
function searches the file for the resource. 


dwResLen 
_ Specifies the buffer size, in bytes, identified by the IpvData parameter. The Get- 
FileResourceSize function returns the buffer size required to hold the resource. 


If the buffer is not large enough, the resource e data i iS truncated to the size of the 
buffer. | 
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lpvData 
Points to the buffer that will receive a copy of the resource. If the buffer is not 
large enough, the resource data is truncated. 


Return Value _ The return value is nonzero if the function is successful. Otherwise, it is zero, indi- 
cating the function could not find the file, could not find the resource, or produced 
an MS-DOS error. The GetFileResource function returns no information about 
the type of error that occurred. 


Comments If the dwFileOffset parameter is zero, the GetFileResource function determines 
the location of the resource by using the /pszResType and IpszResID parameters. 


If dwFileOffset is not zero, GetFileResource assumes that dwFileOffset is the re- 
turn value of GetFileResourceSize and, therefore, ignores [pszResType and 
[pszResID. 


See Also GetFileResourceSize 


GetFileResourceSize 3.4 


#include <ver.h> 


DWORD GetFileResourceSize(/pszFileName, lpszResType, lpszResID, lpdwF psa 


LPCSTR [pszFileName; /* address of buffer for filename 

LPCSTR IpszResType; /* address of buffer for resource type * 
LPCSTR I[pszResID; /* address of buffer for resource ID */ 
DWORD FAR *lpdwFileOffset; /* address of resource offset in file */ 


The GetFileResourceSize function searches the specified file for the resource of 
the specified type and identifier. 


_ Parameters [pszFileName | | 
| Points to the buffer that contains the name of the file in which to search for the 

resource. 

_lpszResType 
Points to a value that is created by using the MAKEINTRESOURCE macro 
with the numbered resource type. This value is typically VS_FILE_INFO. 

lpszResID 

Points to a value that is created by using the MAKEIN TRESOURCE macro 


with the numbered resource identifier. This value is typically 
VS_VERSION_INFO. 


Return Value 


See Also 


GetFileTitle 
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IpdwFileOffset 
Points to a 16-bit value that the GetFileResourceSize function fills with the off- 
set to the resource within the file. 


The return value is the size of the resource, in bytes. The return value is NULL if 
the function could not find the file, the file does not have any resources attached, 
or the function produced an MS-DOS error. The GetFileResourceSize function re- 
turns no information about the type of error that occurred. 


GetFileResource 


#include <commdlg.h> 


int GetFileTitle(/pszFile, lpszTitle, cbBuf) 


LPCSTR I[pszFile; 
LPSTR [pszTitle; 
—UINT cbBuf; 


Parameters 


Return Value 


Comments 


/* pointer to filename (including drive and directory) a | 

/* address of buffer that receives filename ‘a 

/* length of buffer | | sa 
The GetFileTitle function returns the title of the file identified by the lpszF le pa- 
rameter. 
lpszFile- 


Points to the name and location of an MS-DOS file. 


IpszTitle 


Points to a buffer into which the function is to copy the name of the file. 


cbBuf 


Specifies the length, in hit of the buffer to which the lpszTitle parameter 
points. : | 


The return value is zero if the function is successful. The return value is a negative 
number if the filename is invalid. The return value is a positive integer that speci- 
fies the required buffer size, in bytes, if the buffer to which the /pszTitle parameter 


- points is too small. 


_ The function returns an error value if the buffer pointed to by the IpszF ile parame- 


ter contains any of the following: 


om An empty string 


os A Strung: containing a wildcard (*), opening ‘bracket (LD, or losing bracket (]) 
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= A string that ends with a colon (:), slash mark (/), or backslash (\) 
= A string whose length exceeded the length of the buffer 


= An invalid character (for example, a space or unprintable character). 


The required buffer size includes the terminating null character. 


~GetFileVersioninfo = aay 


#include <ver.h> 


BOOL GetFileVersionInfo(/pszFileName, handle, cbBuf, lpvData) 


LPCSTR I[pszFileName; /* address of buffer for filename */ 
DWORD handle; /* file-version information */ 
DWORD cbBif; /* size of buffer */ 
void FAR® [pvData; /* address of buffer for file-version info */ 


The GetFileVersionInfo function returns version information about the specified 
file. The application must call the GetF ile VersionInfoSize function before calling 
GetFileVersionInfo to obtain the appropriate handle if the handle is not NULL. 


Parameters lpszFileName 
Points to the buffer that contains the name of the file. 


handle 
Identifies the file-version information. The GetFileVersionInfoSize function 
returns this handle, or it may be NULL. If the handle parameter is NULL, the 
GetFileVersionInfo function searches the file for the version information. 


cbBuf | 
Specifies the buffer size, in bytes, identified by the /pvData parameter. The Get- 
File VersionInfoSize function returns the buffer size required to hold the file- 
version information. If the buffer is not large enough, the file-version 
information is truncated to the size of the buffer. 


lpvData 


Points to the buffer that will receive the file-version information. This parame- 
ter is used by a subsequent call to the VerQuery Value function. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero, indi- 
cating the file does not exist or the handle parameter is invalid. The GetFile- 


VersionInfo function returns no information about the type of error that occurred. 


Comments The file version information is organized in a VERSIONINFO statement. 
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Currently, the GetFileVersionInfo function recognizes only version-information 
created by Microsoft Resource Compiler (RC). 


See Also GetFileVersionInfoSize, VerQueryValue 


GetFileVersioninfoSize Ot 
#include <ver.h> | os | 


DWORD GetFileVersionInfoSize(/pszFileName, lpdwHandle) | 
LPCSTR /pszFileName; /* address of buffer for filename #) 
DWORD FAR */pdwHandle; /* address of handle forinfo *) 


The GetFileVersionInfoSize function determines whether it can obtain version in- 
formation from the specified file. If version information is available, GetFile- 
VersionInfoSize returns the size of the buffer required to hold the version 
information. It also returns a handle that can be used in a subsequent call to the 
GetFileVersionInfo function. 


Parameters lpszFileName © 
Points to the buffer that contains the name of the file. 


lpdwHandle ; 
Points to a 32-bit value that the GetFile VersionInfoSize function fills with the 
handle to the file-version information. The GetFileVersionInfo function can 
use this handle. 


Return Value The return value is the buffer size, in bytes, required to hold the version informa- 
| tion if the function is successful. The return value is NULL if the function could 
not find the file, could not find the version information, or produced an MS-DOS 
error. The GetFileVersionInfoSize function returns no information about the 2 ype 
of error that occurred. | 


: Comments om Th he file version information is organized in a VERSIONINFO statement. 


See Also 7 GetFileVersionInfo | 


376 GetFocus 


GetFocus = rae) 


HWND GetFocus(void) — 
The GetFocus function retrieves the handle of the window that currently has the 
input focus. 

Parameters This function has no parameters. 

Return Value The return value is the handle of the focus window. If no window has the focus, it 
is NULL. | 

See Also GetActiveWindow, GetCapture, SetFocus 


GetFontData [aa] 


DWORD GetFontData(hdc, dwTable, dwOffset, lpvBuffer, a 


HDC hdc; /* handle of device context 

DWORD dwTable; /* metric table to query _ 
DWORD dwOffset; /* offset into table being queried | 
void FAR* IpvBuffer; /* address of buffer for font data ay 
DWORD cbData; /* length of data to query st | 


The GetFontData function retrieves font-metric information from a scalable font 
file. The information to retrieve is identified by specifying an offset into the font 
file and the length of the information to return. 


Parameters | hdc 
| Identifies the device context. 


dwTable 
Specifies the name of the metric table to be returned. This parameter can be one 
of the metric tables documented in the TrueType Font Files specification, pub- — 
lished by Microsoft Corporation. If this parameter is zero, the information is re- 
trieved starting at the beginning of the font file. 


dwOffset 
Specifies the offset from the beginning of the table at which to begin meine 
information. If this parameter is zero, the information is retrieved starting at the 
beginning of the table specified by the dwTable parameter. If this value is 
greater than or equal to the size of the table, GetFontData returns zero. 


Return Value 


Comments 


Example 
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lpvBuffer 
Points to a buffer that will receive the font information. If this value is NULL, 
the function returns the size of the buffer required for the font data specified in 
the dwTable parameter. 


cbData 
Specifies the length, in bytes, of the information to be retrieved. If this parame- 
ter is zero, GetFontData returns the size of the data specified in the dwTable 
parameter. 


The return value specifies the number of bytes returned in the buffer pointed to by 
the /pvBuffer parameter, if the function is successful. Otherwise, it is —1. 


An application can sometimes use the GetFontData function to save a TrueType 
font with a document. To do this, the application determines whether the font can 
be embedded and then retrieves the entire font file, specifying zero for the 
dwTable, dwOffset, and cbData parameters. : 


Applications can determine whether a font can be embedded by checking the 
otmfsT ype member of the OUTLINETEXTMETRIC structure. If bit 1 of- 
otmfsType is set, embedding is not permitted for the font. If bit 1 is clear, the font 


can be embedded. If bit 2 is set, the embedding is read-only. 


If an application attempts to use this function to retrieve information for a non- 
TrueType font, the GetFontData function returns. —1, | 


The following example retrieves an entire TrueType font file: 


HGLOBAL hg1b; 


DWORD dwSize; 


void FAR* IpvBuffer; 


dwSize = GetFontData(hdc, NULL, @L, NULL, @L); /* get file size */ 


hglb = GlobalAlloc(GPTR, dwSize); /* allocate memory */. 
lpvBuffer = GlobalLock(hglb); | ; | a 
GetFontData(hdc, NULL, OL, IpvBuffer, dwSize); /* retrieve data * / 


The following retrieves an entire TrueType font file 4K at a time: 


#define SIZE 4096 
BYTE Buffer[SIZE]; 
DWORD dwOffset; 
DWORD dwSize; 
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See Also 


dwOffset = @L; 


while(dwSize = GetFontData(hdc, NULL, dwOffset, Buffer, SIZE)) { 


. /* process data in buffer */ 


dwOffset += dwSize; 
} 


The following example retrieves a TrueType font table: 


HGLOBAL hgIb; 
DWORD dwSize; 


void FAR* lpvBuffer; 


LPSTR IpszTable; 
DWORD dwTable; 


lpszTable 
dwlable 


"cmap"; 
*(LPDWORD) IpszTable; 


/* construct DWORD type */ 


dwSize = GetFontData(hdc, dwlable, @L, NULL, @L); /* get table size */ 


hglb = GlobalAlloc(GPTR, dwSize); 
lpvBuffer = GlobalLock(hglb); 


/* allocate memory */ 


GetFontData(hdc, dwlable, OL, IpvBuffer, dwSize); /* retrieve data */ 
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GetFreeFileHandles 


#include <stress.h> 


int GetF reeFileHandles(void) 


Parameters 


Return Value 


EXE 


The GetFreeFileHandles function returns the number of file handles available to 


the current instance. 


This function has no parameters. 


The return value is the number of file handles available to the current instance. 
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GetFreeSpace ; 


DWORD GetFreeSpace(fuF lags) 
UINT fuFlags; /* ignored in Windows 3.1 °) 


The GetFreeSpace function scans the global heap and returns the number of bytes 
of memory currently available. 


Parameters fuFlags 
: This parameter is ignored in mAnGOws 3.1, 
Return Value The return value is the amount af available memory, in bytes, if the function is _ 
successful. 
— Comments © The amount of memory specified by the return value is not necessarily contiguous; : 


the GlobalCompact function returns the number of bytes in the largest block of 
free global memory. | 


In standard mode, the value returned represents the number of bytes in the global 
heap that are not used and that are not reserved for code. 


In 386-enhanced mode, the return value is an estimate of the amount of memory 
available to an application. It does not account for memory held in reserve for non- 
Windows applications. 


See Also GlobalCompact 


GetFreeSystemResources Ba 


UINT GetFreeSystemResources(fuSysResource) | 
UINT fuSysResource; _—s*/* type of resource to check */ 


The GetFreeSystemResources function returns the percentage of free space for 
system resources. 


Parameters fuSysResource 
Specifies the type of resource to be checked. This parameter can be one of the 
following values: | 
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Value Meaning | 

GFSR_SYSTEMRESOURCES Returns the percentage of free space for system 
resources. | 

GFSR_GDIRESOURCES Returns the percentage of free space for GDI re- 


sources. GDI resources include device-context 
handles, brushes, pens, regions, fonts, and bit- 
-_-‘ maps. . 
GFSR_USERRESOURCES Returns the percentage of free space for USER 
resources. These resources include window and 
menu handles. 


Return Value The return value specifies the percentage of free space for resources, if the func- 
tion is successful. 


Comments Since the return value from this function does not guarantee that an application 
will be able to create a new object, applications should not use this function to de- 
termine whether it will be possible to create an object. 


See Also GetFreeSpace 


GetGlyphOutline : [3.1 | 


DWORD GetGlyphOutline(hdc, uChar, fuFormat, Ipgm, chBuffer, lpBuffer, [pmat2) 


HDC hdc; /* handle of device context a 
UINT uChar; | /* character to query a ) 
UINT fuFormat; /* format of data to return pa 
~LPGLYPHMETRICS Ipgm; /* address of structure with glyph metrics | 
DWORD cbBuffer; /* size of buffer for data ob 
void FAR* [pBuffer; /* address of buffer for outline data ey 
LPMAT2 [pmai2; /* address of structure with transform matrix i 


The GetGlyphOutline function retrieves the outline curve or bitmap for an out- _ 
line character in the current font. 


Parameters hdc. 
Identifies the device context. 
uChar | | 
Specifies the character for which information is to be returned. 
fuFormat . | : 
Specifies the format in which the function is to return information. It can be one 
of the following values: | 
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Value Meaning 


GGO_BITMAP Returns the glyph bitmap. When the function returns, the buffer 
pointed to by the JpBuffer parameter contains a 1-bit-per-pixel 
bitmap whose rows start on doubleword boundaries. 

GGO_NATIVE Returns the curve data points in the rasterizer’s native format, 
using device units. When this value is specified, any transforma- 
tion specified in the Ipmat2 parameter is ignored. 


When the value of this parameter is zero, the function fills in a 
GLYPHMETRICS structure but does not return glyph-outline data. 


lpgm 
Points to a GLYPHMETRICS structure that describes the placement of the 
glyph in the character cell. The GLYPHMETRICS structure has the following 
form: 


typedef struct tagGLYPHMETRICS { /* gm */ 
UINT gmBlackBoxx; 
UINT gmBlackBoxyY; 
POINT gmptGlyphOrigin; 
int gmCellIncx; 
int gmCellincy; 
} GLYPHMETRICS; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


cbBuffer 
Specifies the size of the buffer into which the function copies information about 
the outline character. If this value is zero and the fuFormat parameter is either 
the GGO_BITMAP or GGO_NATIVE values, the function returns the required 
size of the buffer. 


- IpBuffer 
Points to a buffer into which the function copies information about the outline 
character. If the fuFormat parameter specifies the GGO_NATIVE value, the in- 
formation is copied in the form of TTPOLYGONHEADER and TTPOLY- 
CURVE structures. If this value is NULL and the fuFormat parameter is either 
the GGO_BITMAP or GGO_NATIVE value, the function returns the required 
size of the buffer. 


lpmat2 | 
Points to a MAT2 structure that contains a transformation matrix for the charac- 
ter. This parameter cannot be NULL, even when the GGO_NATIVE value is 
specified for the fuFormat parameter. The MAT2 structure has the following 
form: , 


382  GetGlyphOutline 


Return Value 


Comments 


typedef struct tagMAT2 { /* mat2 */ 
FIXED eM11; 
FIXED eM12; 
FIXED eM21; 
FIXED eM22; . 
} MAT2; : 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the size, in bytes, of the buffer required for the retrieved infor- 
mation if the cbBuffer parameter is zero or the [pBuffer parameter is NULL. Other- 
wise, it is a positive value if the function is successful, or —1 if there is an error. 


An application can rotate characters retrieved in bitmap format by specifying a 
2-by-2 transformation matrix in the structure pointed to by the [pmat2 parameter. 


A glyph outline is returned as a series of contours. Each contour is defined by a 
TTPOLYGONHEADER structure followed by as many TTPOLYCURVE 
structures as are required to describe it. All points are returned as POINTF*X< struc- 
tures and represent absolute positions, not relative moves. The starting point given 
by the pfxStart member of the TTPOLYGONHEADER structure is the point at 
which the outline for a contour begins. The TTPOLYCURVE structures that fol- 
low can be either polyline records or spline records. Polyline records are a series 
of points; lines drawn between the points describe the outline of the character. 
Spline records represent the quadratic curves used by TrueType (that is, quadratic 
b-splines). 


For example, the GetGlyphOutline function retrieves the following information 


about the lowercase “1” in the Arial TrueType font: 
dwrc = 88 /* total size of native buffer * / 
- TTPOLYGONHEADER #1 /* contour for dot oni */ 
cb = 44 /* size for contour * / 
dwlype = 24 /* TT_POLYGON_TYPE * / 


pfxStart = 1.000, 11.000 


TTPOLYCURVE #1 
wlype = TIT_PRIM_LINE 


cpfx = 3 
pfxL@] = 1.000, 12.000 
pfx[1] = 2.000, 12.000 | 
pfxl2] = 2.000, 11.000 /* automatically close to pfxStart */ 
TTPOLYGONHEADER #2 /* contour for body of i * / 
cb = 44 
dwlype = 24 /* TT _POLYGON_TYPE * / 


pfxStart = 1.000, 0.000 


See Also 
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TTPOLYCURVE #1 


wlype = TT_PRIM_LINE 

cpfx = 3 

pfx[@] = 1.000, 9.000 

pfx[1] = 2.000, 9.000 | 

pfx[2] = 2.000, 0.000 /* automatically close to pfxStart */ 


GetOutlineTextMetrics 


GetinputState o rox 


BOOL GetInputState(void) 


Parameters 


Return Value 


See Also 


GetinstanceData 


The GetInputState function determines whether there are mouse clicks or key- 
board events in the system queue that require processing. Keyboard events occur 
when a user presses one or more Keys. The system queue is the location in which 
Windows stores mouse clicks and keyboard events. 


This function has no parameters. -— 


The return value is nonzero if the function detects a mouse click or keyboard event 
in the system queue. Otherwise, it is zero. 


EnableHardwarelInput 


int GetInstanceData(hinst, npbData, cbData) 


HINSTANCE hinst; 


BYTE* npbData; 
int cbData; 


Parameters 


/* handle of previous instance */ 
/* address of current instance data buffer gi 
/* number of bytes to transfer 7 ia 


The GetInstanceData function copies data from a previous instance of an applica- 
tion into the data area of the current instance. ~ 


hinst 
Identifies a previous instance of the application. 
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npbData 
Points to a buffer in the current instance. 


cbData < 
Specifies the number of bytes to be copied. 


Return Value The return value specifies the number of bytes copied if the function is successful. 
Otherwise, it is zero. 


GetKBCodePage 


int GetKBCodePage(void) 


The GetK BCodePage function returns the current Windows code page. 


Parameters This function has no parameters. 
Return Value The return value specifies the code page currently loaded by Windows, if the func- 
tion is successful. It can be one of the following values: 
Value Meaning 
437 Default (United States, used by most countries: indicates that there is no 
OEMANSLBIN in the Windows directory) 
850 International (OQEMANSI.BIN = XLAT850.BIN) 
860 Portugal (OQEMANSI.BIN = XLAT860.BIN) 
861 Iceland (OEMANSI.BIN = XLAT861.BIN) 
863 French Canadian (OQEMANSI.BIN = XLAT863.BIN) 
865 Norway/Denmark (OQEMANSLBIN = XLAT865.BIN) 
Comments The keyboard driver provides the GetKBCodePage function. An application 
using this function must include the following information 1 in its module-definition 
(.DEF) file: 
IMPORTS 


KEYBOARD. GETKBCODEPAGE 


If the OEMANSI. BIN file is in the Windows directory, Windows reads it and over- 
writes the OEM/ANSI translation tables in the keyboard driver. 


When the user selects a language from the Setup program and the language does 
- not use the default code page (437), Setup copies the appropriate file (such as 
XLAT850.BIN) to OEMANSLBIN in the Windows system directory. If the lan- 
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guage uses the default code page, Setup deletes OEMANSI.BIN, if it exists, from 
the Windows system directory. 


Example The following example uses the ee Codehace function to display the current 
code page: 


char szBuf[8Q@]; 
int i, cp, subtype, f_keys, len; 


char *apszKeyboards[] = { 


"IBM PX/XT", 
"Olivetti ICO", 
"IBM AT", 


"IBM Enhanced", 
"Nokia 1050", 

"Nokia 9140", 
"Standard Japanese", 
}; 


cp = GetKBCodePage(); 


if (Ci = GetKeyboardType(0)) == @ || i> 7) { 
MessageBox(NULL, “invalid keyboard type”, 
"GetKeyboardType", MB_ICONSTOP); 
break; | 
} 


subtype = GetKeyboardType(1); 
f_keys = GetKeyboardType(2); 


len = wsprintf(szBuf, "%s keyboard, subtype %d\n", 
apszKeyboards[i - 1], subtype); 

len = wsprintf(szBuf + len, " %4d function keys, code page %d", 
f_keys, cp); 


MessageBox(NULL, szBuf, “Keyboard Information", MB_OK); 


See Also | GetKeyboardType 


-GetKerningPairs — bedi! oo [3.1 | 


int GetKerningPairs(hdc, eee [pkrnpair) 

HDC hdc; /* handle of device context | oh 
int cPairs; /* number of kerning pairs ‘| 
KERNINGPAIR FAR* * inkrhpairs __-/* pointer to structures for kerning pairs | 
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Parameters 


Return Value 


The GetKerningPairs function retrieves the character kerning pairs for the font 
that is currently selected in the specified device context. 


hdc 


Identifies a device context. The GetKerningPairs function retrieves kerning 
pairs for the current font for this device context. 


cPairs 
Specifies the number of KERNINGPAIR structures pointed to by the 
Ipkrnpair parameter. The function will not copy more kerning pairs than 
specified by cPairs. 


The KERNINGPAIR structure has the following form: — 


typedef struct tagKERNINGPAIR { 
WORD wFirst; 
WORD wSecond; 
int ikKernAmount; 

} KERNINGPAIR; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


lpkrnpair 
Points to an array of KERNINGPAIR structures that receive the kerning pairs 
when the function returns. This array must contain at least as many structures as 
specified by the cPairs parameter. If this parameter is NULL, the function re- 
turns the total number of kerning pairs for the font. 


The return value specifies the number of kerning pairs retrieved or the total num- 
ber of kerning pairs in the font, if the function is successful. It is zero if the func- 
tion fails or there are no kerning pairs for the font. 
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void GetK eyboardState(jpbKeyState) | , 
BYTE FAR®* [pbKeyState; /* address of array to receive virtual- key codes =] 


Parameters 


Return Value 


The GetKeyboardState function copies the status of the 256 virtual- “keyboard 
Keys to the specified buffer. 


IpbKeyState | 
Points to the 256- byte buffer that will receive the virtual- key codes. 


This function does not return a value. 
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Comments An application calls the GetKeyboardState function in response to a keyboard- 
input message. This function retrieves the state of the keyboard at the time the 
input message was generated. 


If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 
1, the key is toggled. A toggle key, such as the CAPSLOCK key, is toggled if it has 
been pressed an odd number of times since the system was started. The key is un- 
toggled if the low-order bit is 0. . 


For a list of virtual-key codes and their corresponding mouse or keyboard equiv- 
alents, see the Microsoft Windows Programmer’s Reference, Volume 3. 


Example The following example simulates a pressed CTRL key: 
BYTE pbKeyState[256]; 
GetKeyboardState((LPBYTE) &pbKeyState) ; 


pbKeyState[VK_CONTROL] |= @x8@; 
SetKeyboardState((LPBYTE) &pbKeyState) ; 


See Also GetKeyState, SetKeyboardState 


GetKeyboardType — 


int GetKeyboardType({nKeybinfo) 
int fnKeybInfo; /* specifies type of information to retrieve */ 


The GetKeyboardType function retrieves information about the current keyboard. 
Parameters _ fnKeybInfo 


Determines the type of keyboard information to be retrieved. This parameter 
can be one of the following values: | 


Value Meaning 
Q- Retrieves the keyboard type. 
1 Retrieves the keyboard subtype. 
2 og: Retrieves the number of function keys on the keyboard. 
- Return Value The return value specifies the requested information if the function | iS successful. 


| Otherwise, it is Zero. 


| Comments The subtype is an OEM- dependent value The sty may be one of the follow: 
ing values: | vo 
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Value Meaning 
1 IBM PC/XT, or compatible (83-key) keyboard 
2 Olivetti “ICO” (102-key) keyboard 
7 IBM AT (84-key) or similar keyboard 
4 IBM Enhanced (101- or 102-key) keyboard 
5 Nokia 1050 and similar keyboards 
6 Nokia 9140 and similar keyboards 
7 Japanese keyboard 


The keyboard driver provides the GetKeyboardType function. An application 
using this function must include the following information in its module-definition 
(.DEF) file: 


IMPORTS 
KEYBOARD. GETKEYBOARDTY PE 


The application can also determine the number of function keys on a keyboard 
from the keyboard type. The number of function keys for each keyboard type fol- 
lows: 


Type Number of function keys 


1 10 | 

2 12 (sometimes 18) 

3 10 

4 12 

5 10 

6 24 

7 This value is hardware-dependent and must be specified by the OEM. 
Example The following example uses the GetKeyboardType function to clspiay informa- 


tion about the current keyboard: 


char szBuf[8@]; 
int i, cp, subtype, f_keys, len; 


char *apszKeyboards[] = { 
"IBM PX/XT", 
"Olivetti ICO", 
“IBM AT", 
"IBM Enhanced", 
"Nokia 1050", 
"Nokia 9140", 
“Standard Japanese", 
3 
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cp = GetKBCodePage(); 


if ((i = GetKeyboardType(@)) == @ || i> 7) { 
MessageBox(NULL, "invalid keyboard type", 

"GetKeyboardType", MB_ICONSTOP); 
break; 


I 


subtype = GetKeyboardType(1); 
f_keys = GetKeyboardType(2); 


len = wsprintf(szBuf, "%s keyboard, subtype %d\n", 
apszKeyboards[i - 1], subtype); | 

len = wsprintf(szBuf + len, " %d function keys, code page %d", 
f_keys, cp); 


~ MessageBox(NULL, szBuf, "Keyboard Information", MB_OK); 


-GetKeyNameText 


int GetKeyNameText(/Param, lpszBuffer, cbMaxKey) 


LONG [Param — /* 32-bit parameter of keyboard message *] 
LPSTR I[pszBuffer; /* address of a buffer for key name | */ 
int cbMaxKey; /* specifies maximum key string length */ 
The GetKeyNameText function retrieves a string that represents the name of a 
key. 
Parameters [Param 


Specifies the 32-bit parameter of the keyboard message (such as 
~ WM_KEYDOWN) to be processed. The GetKeyNameText function interprets 
_ the following portions of /Param: 


Bits Meaning 

16-23 Character scancode. | : | 

24 Extended bit. Distinguishes some keys on an enhanced keyboard. 

25 “Don’t care” bit. The application calling this function sets this bit to indi- 


cate that the function should not distinguish between left and right CTRL — 
and SHIFT keys, for example. eee 


lpszBuffer | 
Points to a buffer that will receive > the key name. 
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cbMaxKey 
Specifies the maximum length, in bytes, of the key name, not including the ter- 
minating null character (this parameter should one less than the size of the buff- 
er pointed to by the lpszBuffer parameter). 


Return Value The return value is the length, in bytes, of the string copied to the specified buffer, 
| if the function is successful. Otherwise, it is zero. 


Comments The format of the key-name string depends on the current keyboard driver. This 
driver maintains a list of names in the form of character strings for keys with 
names longer than a single character. The key name is translated, according to the 
layout of the currently installed keyboard, into the principal language supported by 
the keyboard driver. 


GetKeyState Oo rex | 


int GetKeyState(vkey) 
int vkey; /* virtual key */ 


The GetKeyState function retrieves the state of the specified virtual key. The state 
specifies whether the key is up, down, or toggled (on, off—alternating each time 
the key is pressed). 


Parameters vkey 
Specifies a virtual key. If the requested virtual Key is a letter or digit (A through 
Z, a through z, or 0 through 9), vkey must be set to the ASCII value of that char- 
acter. For other Keys, it must be a virtual-key code. For a list of virtual-key 
codes, see the Microsoft Windows Programmer’s Reference, Volume 3. 


Return Value The return value specifies the state of the given virtual key. If the high-order bit is 
1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. 
A toggle key, such as the CAPSLOCK key, is toggled if it has been pressed an odd 
number of times since the system was started. The key is untoggled if the low- 
order bit is 0. | 


Comments An application calls the GetKeyState function in response to a keyboard-input 
message. This function retrieves the state of the key at the time the input message 


was generated. 


See Also | | GetAsyncKeyState, GetKeyboardState 
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GetLastActivePopup 
HWND GetLastActivePopup(hwndOwner) 
HWND hwndOwner; /* handle of owner window i | 


The GetLastActivePopup function determines which pop-up window owned by 
the given window was most recently active. 


Parameters hwndOwner 
Identifies the owner window. 


Return Value The return caldes is the handle of most-recently active pop-up window if the func- 
tion is successful. 


Comments The return value handle will be the same as the handle in the hwndOwner parame- 
ter if any of the following conditions are met: 


= The window identified by hwndOwner was most recently active. 
= The window identified by hwndOwner does not own any pop-up windows. | 


= The window identified by hwndOwner is not a top-level window or is owned 
by another window. 


See Also AnyPopup, GetActiveWindow, ShowOwnedPopups 


GetMapMode — = x] 
int GetMapMode(hdc) | 
HDC hdc; /* handle of device context */ 


The GetMapMode function retrieves the current mapping mode. 


Parameters §§s hde—t 
| ee ot Identifies the device context. 


Return Value = —‘ The return value specifies the mapping tide if the function is successful. 
~ Comments For a complete list of mapping modes, see the description of the SetMapMode 
i. function. 
Example The following example uses the GetMapMode function to determine whether the 


current mapping mode 1 is MM_ eee 
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Return Value 


See Also 


if (GetMapMode(hdc) != MM_TEXT) { 
TextOut(hdc, 100, -20@, "Mapping mode must be MM_TEXT"™, 28); 
return FALSE; 


} 
See Also SetMapMode 
GetMenu Ea 
HMENU GetMenu(hwnd) 
HWND hwnd; /* handle of window */ 
The GetMenu function retrieves the handle of the menu associated with the given 
window. 
Parameters hwnd 


Identifies the window whose menu handle is retrieved. 


The return value is the handle of the menu if the function is successful. It is NULL 
if the given window has no menu. It is undefined if the window is a child window. 


GetSubMenu, SetMenu 


GetMenuCheckMarkDimensions 


DWORD GetMenuCheckMarkDimensions(void) 


Parameters 


The GetMenuCheckMarkDimensions function returns the dimensions of the de- 
fault check mark bitmap. Windows displays this bitmap next to checked menu 
items. Before calling the SetMenuItemBitmaps function to replace the default 
check mark, an application should determine the correct size for the bitmaps by 
calling the GetMenuCheckMarkDimensions function. 


This function has no parameters. 
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Return Value The low-order word of the return value contains the width, in pixels, of the default 
| check mark bitmap, if the function is successful; the high-order word contains the 
height. | 
See Also SetMenultemBitmaps 


GetMenultemCount - [ 2x | 


int GetMenultemCount(imenu) 
HMENU hmenu; /* handle of menu */ 


The GetMenulItemCount function determines the number of items in a pop-up or 
top-level menu. 


"Parameters hmenu | a 
Identifies the handle of the menu to be examined. 


Return Value The return value specifies the number of items in the menu if the function is 
| successful. Otherwise, it is —1. 


Example The following example initializes the items in a pop-up menu: 


WORD wCount; 
WORD witen; 
WORD wID; 


case WM_INITMENUPOPUP: 
wCount = GetMenuItemCount((HMENU) wParam); 
for (wiItem = 0; witem < wCount; witem++) { 
wID = GetMenuItemID((HMENU) wParam, witem); 
. /* Initialize menu items. */ 
+ 
break; 


See Also” | GetMenu, GetMenultemID, GetSubMenu 
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GetMenultemID — oa 


UINT GetMenultemID(hmenu, pos) 
HMENU hmenu; /* handle of menu */ 
int pos; _/* position of menu item */ 


The GetMenultemID function retrieves the identifier for a menu item located at 
the given position. 


Parameters hmenu 


Identifies the pop-up menu that contains the item whose identifier is to be re- 
trieved. 


pos 
Specifies the zero-based position of the menu item whose identifier is to be re- 
trieved. 


Return Value The return value specifies the identifier of the pop-up menu item if the function is 
successful. If the hmenu parameter is NULL or if the specified item is a pop-up 
menu (as opposed to an item within the pop-up menu), the return value is —1. If 
the pos parameter corresponds to a SEPARATOR menu item, the return value is 
zero. | : | 


Example _ The following example initializes the items in a pop-up menu: 


WORD wCount; 
WORD witem; 
WORD wID; 


case WM_INITMENUPOPUP: 
wCount = GetMenultemCount((HMENU) wParam) ; 
for (wItem = @; wiItem < wCount; witem++) { 
wID = GetMenuItemID((HMENU) wParam, witem); 


. /* Initialize menu items. */ 


I 
break; 


See Also | GetMenu, GetMenulItemCount, GetSubMenu 
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GetMenuState rex] 


UINT GetMenuState(hmenu, idltem, fuFlags) 


HMENU hmenu; 
UINT idltem; 
UINT fuFlags; 


Parameters 


Return Value 


/* handle of menu **/ 
/* menu-item identifier */ 
/* menu flags */ 


The GetMenuState function retrieves the status flags associated with the 
specified menu item. If the menu item is a pop-up menu, this function also returns 
the number of items in the pop-up menu. 7 


hmenu 
Identifies the menu. 
idIltem | | | 
Specifies the menu item for which the state is retrieved, as determined by the 
_ fuFlags parameter. | 
fuFlags 
Specifies the nature of the idl/tem parameter. It can be one of the following 
values: 


Value Meaning 
MF_BYCOMMAND Specifies the menu-item identifier. 
MF_BYPOSITION Specifies the zero-based position of the menu item. 


The return value is —1 if the specified item does not exist. If the id/tem parameter 
identifies a pop-up menu, the high-order byte of the return value contains the num- 
ber of items in the pop-up menu, and the low order byte contains the menu flags 
associated with the pop-up menu. Otherwise, the return value is a mask (Boolean 
OR) of the values from the following list (this mask describes the status of the _ 
menu item that idltem identifies): | 


Value Meaning 

MF_BITMAP Item is a bitmap. 

MF_CHECKED Check mark is placed next to item (pop-up menus only). 
MF_DISABLED Item is disabled. 

MF_ENABLED Item is enabled. Note that the value of this constant is 


zero; an application should not test against zero for 
failure when using this value. | 


MF_GRAYED _ Item is disabled and grayed. 


MF_MENUBARBREAK Same as MF_MENUBREAK, except for pop-up menus 
where the new column is separated from the old column 
by a vertical dividing line. 
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Value | Meaning 
MF_MENUBREAK Item is placed on a new line (static menus) or in a new 
column (pop-up menus) without separating columns. 


MF_SEPARATOR Horizontal dividing line is drawn (pop-up menus only). 
| This line cannot be enabled, checked, grayed, or 
highlighted. The id/tem and fuFlags parameters are ig- 
nored. 

MF_UNCHECKED Check mark is not placed next to item (default). Note 
that the value of this constant is zero; an application 
should not test against zero for failure when using this 
value. 


Example The following example retrieves the handle of a pop-up menu, retrieves the 
checked state of a menu item in the menu, and then toggles the checked state of 
the item: 


HMENU hmenu; 
BOOL fOwnerDraw; 


/* Retrieve a handle to the Colors menu. */ 
hmenu = GetSubMenu(GetMenu(hwnd), ID_COLORS_ POS); 
/* Retrieve the current state of the item. */ 


fOwnerDraw = GetMenuState(hmenu, IDM _COLOROWNERDR, 
MF_BYCOMMAND) & MF_CHECKED; 


/* Toggle the state of the item. */ 


CheckMenuItem(hmenu, IDM _COLOROWNERDR, ) 
MF_BYCOMMAND | (fOwnerDraw ? MF_UNCHECKED : MF_CHECKED)); 


See Also ~ GetMenu, GetMenulItemCount, GetSubMenu 


GetMenuString 397 


GetMenuString 2x] 


int GetMenuString(imenu, idltem, lpsz, chMax, fwF wea 
HMENU hmenu; /* handle of menu 


UINT idltem; /* menu-item identifier i 
LPSTR l[psz; /* address of buffer for label i 
int cbMax; /* maximum length of label x} 
UINT fwFlags; /* menu flags */ 


The GetMenuString function copies the label of a menu item into a buffer. 


Parameters hmenu 
Identifies the menu. 


idltem , 
Specifies the menu item whose label i is to be copied, as determined by the 
fwFlags parameter. 


[psz 
Points to a buffer that will receive the null-terminated label string. 
cbMax 


Specifies the maximum length, in bytes, of the label string. The label string is 
truncated if it is longer. 


fwFlags 
Specifies the nature of the idltem parameter. It can be one of the following 
values: 
Value Meaning 
MF_BYCOMMAND Specifies the menu-item identifier. 
MF_BYPOSITION Specifies the zero-based position of the menu item. 
Return Value The return value is the length, in bytes, of the returned label, if the function is 


successful. The length does not include the terminating null character. 


Comments | The cbMax parameter should be one larger than the number of characters in the 
label to accommodate the null character that terminates the string. 


See Also GetMenu, GetMenultemID 
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GetMessage 


BOOL GetMessage(/pmsg, hwnd, uMsgFilterMin, uMsgFilterMax) 


MSG FAR® Ipmsg; /* address of structure with message **/ 

HWND hwnd; /* handle of the window | */ 

UINT uMs¢gFilterMin; /* first message , i 

UINT uMsgFilterMax; -/* Jast message uh 
The GetMessage function retrieves a message from the application’ S message 
queue and places the message in a MSG structure. If no message is available, Get- 
Message yields control to other applications until a message becomes available. 
GetMessage retrieves messages associated only with the given window and 
within the given range of message values. The function does not retrieve messages 
for windows that belong to other applications. 

Parameters Ipmsg 


Return Value 


Points to an MSG structure that contains message information from the applica- 
tion’s message queue. The MSG structure has the following form: 


typedef struct tagMSG {- /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 

hwnd 
Identifies the window whose messages are to be retrieved. If this parameter is 
NULL, GetMessage retrieves messages for any window that belongs to the ap- 
plication making the call. 


uMsgFilterMin 
Specifies the integer value of the lowest peer value to be retrieved. 


uMsgFilterMax 
Specifies the integer value of the highest message value to be retrieved. 


The return value is nonzero if a message other than WM _QUITi is retrieved. It i 1S 
zero if the WM_QUIT message is retrieved. 
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Comments The return value is usually used to decide whether to terminate the application’s 
main loop and exit the program. 


The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values 
to retrieve all messages related to keyboard input; the WM_MOUSEFIRST and 
-WM_MOUSELAST constants can be used to retrieve all mouse-related messages. 
If the uMsgFilterMin and uMsgFilterMax parameters are both zero, the Get- 
Message function returns all available messages (without performing ay 

_ filtering). 


In addition to yielding control to other applications when no messages are availa- 
ble, the GetMessage and PeekMessage functions also yield control when 
WM_PAINT or WM_TIMER messages for other tasks are available. 


The GetMessage, PeekMessage, and WaitMessage functions are the only ways 
to let other applications run. If your application does not call any of these func- 
tions for long periods of time, other applications cannot run. 


Example The following example uses the GetMessage function to retrieve messages from a 
message queue, translates virtual-key messages into character messages, and dis- 
patches messages to the appropriate window procedures: 


MSG msg; 


while (GetMessage(&msg, (HWND) NULL, @, @)) { 
TranslateMessage(&msg); 
DispatchMessage(&msg) ; 

} 


See Also GetMessageExtraInfo, PeekMessage, sea SetMessageQueue, 
| WaitMessage 


GetMessageExtralInfo it een ce 


LONG GetMessageExtraInfo(void) 


The GetMessageExtraInfo function retrieves the extra information associated 

with the last message retrieved by the GetMessage or PeekMessage function. 

This extra information may be added to a message by the driver for a Pouiing 
device or keyboard. , 


Parameters This function has no parameters. 
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Return Value The return value specifies the extra information if the function is successful. The 
meaning of the extra information is device-specific. 


See Also GetMessage, hardware_event, PeekMessage 


GetMessagePos _ Ea 
DWORD GetMessagePos(void) 


The GetMessagePos function returns a long value that represents a cursor posi- 
tion, in screen coordinates. This position is the point occupied by the cursor when 
the last message retrieved by the GetMessage function occurred. | 


Parameters _ This function has no parameters. 


Return Value The return value specifies the x- and y-coordinates of the cursor position if the 
: function is successful. 


Comments To retrieve the current position of the cursor instead of the position at the time the 
last message occurred, use the GetCursorPos function. 


The x-coordinate is in the low-order word of the return value; the y-coordinate 

is in the high-order word. If the return value is assigned to a variable, you can 
use the MAKEPOINT macro to obtain a POINT structure from the return value. 
You can also use the LOWORD or HIWORD macro to extract the x- or the 
y-coordinate. 


See Also GetCursorPos, GetMessage, GetMessageTime. 


GetMessageTime — _ | rox] 


LONG GetMessageTime(void) - 


The GetMessageTime function returns the message time for the last message re- 
trieved by the GetMessage function. The time is a long integer that specifies the 
_ elapsed time, in milliseconds, from the time the system was started to the time the 
_message was created (placed in the application queue). 


Parameters | This function has no parameters. 


Return Value 


Comments 


See Also 


GetMetaFile 
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The return value specifies the message time if the function is successful. 


The return value of the GetMessageTime function does not necessarily increase 
between subsequent messages, because the value wraps to zero if the timer count 
exceeds the maximum value for long integers. 


To calculate time delays between messages, verify that the time of the second mes- 
sage is greater than the time of the first message and then subtract the time of the 
first message from the time of the second message. 


GetMessage, GetMessagePos 


HMETAFILE GetMetaFile(/pszFile) 


LPCSTR [pszFile; 


Parameters 


Return Value 


Example 


/* address of metafile name a | 


The GetMetaFile function creates a handle of a specified metafile. 


lpszFile 
Points to the null-terminated string that specifies the MS-DOS filename of the 
metafile. The metafile is assumed to exist. 7 


The return value is the handle of a metafile if the function is successful. Other- 
wise, itis NULL. 


The following example uses the CopyMetaFile function to copy a metafile to a 
specified file, plays the copied metafile, uses the GetMetaFile function to retrieve 
a handle to the copied metafile, uses the SetWindowOrg function to change the 
position at which the metafile is played 200 logical units to the right, and then 
plays the metafile at the new location: 


HANDLE hmf, hmfSource, hmf0Old; 
LPSTR IpszFilel = "MFTest"; 


hmf = CopyMetaFile(hmfSource, IpszFilel); 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf) ; 


hmfOld = GetMetaFile(lpszFilel); 
SetWindowOrg(hdc, -200, @); 
PlayMetaFile(hdc, hmf0ld); 
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See Also 


GetMetaFileBits 


DeleteMetaFile(hmfSource) ; 
DeleteMetaFile(hmf0Old); 


CopyMetaFile, PlayMetaFile, SetWindowOrg 


[ 2.x | 


HGLOBAL GetMetaFileBits(hm/f) 


HMETAFILE himf; 


Parameters 


Return Value 


Comments 


See Also 


GetModuleFileName 


/* handle of metafile */ 


The GetMetaFileBits function returns a handle of the global memory object that 
contains the specified metafile as a collection of bits. The memory object can be 
used to determine the size of the metafile or to save the metafile as a file. The 
memory object should not be modified. 


hmf 
Identifies the memory metafile. 


The return value is the handle of the global memory object that contains the meta- 
file, if the function is successful. Otherwise, it is NULL. 


The handle contained in the hmf parameter becomes invalid when the GetMeta- 
FileBits function returns, so the returned global no handle must be used to 
refer to the metafile. 


When it no longer requires a global memory object that is associated sith a meta- 
file, an application should remove the object by using the GlobalFree function. 


GlobalFree 


int GetModuleFileName(hinst, lpszFilename, cbFileName) 


HINSTANCE hinst; /* handle of module */ 
LPSTR [pszFilename; /* address of buffer for filename | 
int cbFileName; /* maximum number of bytes to copy re | 


The GetModuleFileName function retrieves the full path and filename of the ex- 
ecutable file from which the specified module was loaded. 


Parameters 


Return Value © 


Example 


See Also 
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hinst 
Identifies the module or the instance of the module. 


lpszF ilename 
Points to the buffer that is to receive the null-terminated filename. 


cbFileName 
Specifies the maximum number of bytes to copy, including the terminating null 
character. The filename is truncated if it is longer than cbFileName. This pa- 
rameter should be set to the length of the filename buffer. 


The return value specifies the length, in bytes, of the string copied to the specified 
buffer, if the function is successful. Otherwise, it is zero. 


The following example retrieves an application’s filename by using the instance 
handle passed to the application in the WinMain function: 


int PASCAL WinMain(HINSTANCE hinst, HINSTANCE hPrevInst, 
LPSTR 1pCmdLine, int nCmdShow) 


{ 

char szModuleName[ 26]; 

GetModuleFileName(hinst, szModuleName, sizeof(szModuleName) ); — 
} e 
GetModuleHandle 


GetModuleHandle — Sere 


HMODULE GetModuleHandle(/pszModuleName) 
LPCSTR /pszModuleName; [ address of name of module */ 


Parameters 


Return Value . | 


See Also 


The GetModuleHandle finction retrieves s the handle of the épseitied module. 


lpszModuleName : 
_ Points toa null- terminated string that sages the name of the module. 


The return value is the handle of the module if the function i iS successful. Other- 
~ wise, it is NULL. . 


| GetModuleFileName 
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GetModuleUsage : [2x] 


int GetModuleUsage(hinst) 
HINSTANCE hinst; — _/* handle of module */ 


The GetModuleUsage function retrieves the reference count of a specified 
module. 


Parameters hinst 
Identifies the module or an instance of the module. 


Return Value The return value specifies the reference count of the module if the function is 
successful. 


Comments — Windows increments (increases by one) a module’s reference count each time an 
application calls the LoadModule function. The count is decremented (decreased 
by one) when an application calls the FreeModule function. 


See Also FreeModule, LoadModule 


GetMsgProc aExE 


LRESULT CALLBACK GetMsgProc(code, wParam, lParam) 
*/ 


int code; /* process-message flag 
WPARAM wParam; /* undefined "i, 
LPARAM /Param; /* pointer to MSG structure sf 


The GetMsgProc function is a library-defined callback function that the system 
calls whenever the GetMessage function has retrieved a message from an applica- 
tion queue. The system passes the retrieved message to the callback function 
before passing the message to the destination window procedure. 


Parameters — code 
Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If this parameter is less than zero, the callback func- 
tion should pass the message to CallNextHookEx without further processing. 


wParam 
Specifies a NULL value. 


lParam 
- Points to an MSG structure that contains information about the message. The 
MSG structure has the following form: 


Return Value 


Comments 


See Also 


GetNearestColor 
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typedef struct tagMSG { | /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


The callback function should return zero. 


The GetMsgProc callback function can examine or modify the message as. 
desired. Once the callback function returns control to the system, the GetMessage 


function returns the message, with any modifications, to the application that origi-. 


nally called it. The callback function does not require a return value. 
This callback function must be in a dynamic-link library (DLL). 


An application must install the callback function by specifying the 
WH_GETMESSAGE filter type and the procedure-instance address of 
the callback function in a call to the SetWindowsHookEx function. 


GetMsgProc is a placeholder for the library- -defined function name. The actual — 
name must be exported by including it in an EXPORTS statement in the library’s 
module-definition (.DEF) file. 


CallNextHookEx, GetMessage. SetWindowsHookEx 


COLORREF GetNearestColor(hdc, clrref) 


HDC hdc; | 


COLORREF cirref: 


Parameters 


/* handle of device context  _*/ 
/* color to match a 


The GetNearestColor fanenions retrieves the solid color that best matches a 


specified logical color; the given device must be able to represent this solid color. 


hdc | 
Identifies the device context. | 


clrref 
ene the éélor to be matched. 
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Return Value The return value specifies an RGB (red, green, blue) color value that defines the 
solid color closest to the clrref value that the device can represent. 


See Also GetNearestPaletteIndex 


GetNearestPalettelndex 


UINT GetNearestPaletteIndex(hpal, clrref) 
HPALETTE hpal; /* handle of palette */ 
COLORREFE cirref; — /* color to match 3 


The GetNearestPaletteIndex function retrieves the index of the logical-palette 
entry that best matches the specified color value. 


Parameters hpal 
Identifies the logical palette. 


clrref 
Specifies the color to be matched. 


Return Value The return value is the index of the logical-palette entry whose corresponding 
color best matches the specified color. 


Example The following example uses the GetNearestPaletteIndex function to retrieve a 
color index from a palette. It then creates a brush with that retrieved color by using 
the PALETTEINDEX macro in a call to the CreateSolidBrush function. 


WORD nColor; 

HPALETTE hpal; 

DWORD dwBrushColors[8][8]; 
HBRUSH hbr; 

int x, y; 


. /* Initialize the array of brush colors. */ 
nColor = GetNearestPaletteIndex(hpal, dwBrushColors[x][y]); 
hbr = CreateSolidBrush(PALETTEINDEX(nColor) ); - 

. /* Use the brush handle. */ 


DeleteObject(hbr) ; 


See Also CreateSolidBrush, GetNearestColor, GetPaletteEntries, 
GetSystemPaletteEntries 
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GetNextDigGroupltem [ex] 


HWND GetNextDigGroupItem(iwndDig, hwndCtrl, fPrevious) 
HWND hwnaDig; /* handle of dialog box **/ 
HWND hwndCtrl; /* handle of control **/ 
BOOL fPrevious; /* direction flag 7 


The GetNextDlgGroupItem function searches for the previous (or next) control 
within a group of controls in a dialog box. A group of controls begins with a con- 
trol with the WS_GROUP style and ends with the last control that does not con- 
taina WS_GROUP style. 


Parameters hwndDlg 
Identifies the dialog box to be searched. 


hwndCtrl 
Identifies the control to be used as the starting point for the search. 


Previous 
Specifies how the function is to search the group of sentoled in the dialog box. 
If this parameter is TRUE, the function searches for the previous control in the 
group. If this parameter is FALSE, the function searches for the next control in 
the group. 


Return Value The return value i is the aiddow handle of the previous (or next) control i inthe — ‘ 
| group, if the function is successful. 


- Comments If the hwndCtrl parameter identifies the last control in the group and the Previous 
} parameter is FALSE, the GetNextDlgGroupItem function returns the window 
handle of the first control in the group. If hwndCtrl identifies the first control in 
the group and {Previous is TRUE, aba eee a a returns the window 
handle of the last control i in the group. 


Example ‘The following example sets the check state of a group of radio buttons. It is as- 
sumed that the group contains only radio buttons and no other type of control: 


HWND hwndStart, hwndCurrent; 


case WM COMMAND: 
switch (HIWORD(1Param)) { 
case BN_CLICKED: 


/* j a? 
* If a radio button was clicked, clear the current 
* selection and select the one that was clicked. 

* / 


hwndStart = GetDigItem(hdlg, wParam); 


408 GetNextDigTabltem 


See Also 


GetNextDigTabltem 


if (LOWORD(GetWindowLong(hwndStart, 
GWL_STYLE) == BS_RADIOBUTTON)) { 
hwndCurrent = hwndStart; 


do { 
hwndCurrent = GetNextDligGroupItem(hdlg, 
hwndCurrent, TRUE); 
SendMessage(hwndCurrent, BM_SETCHECK, 
hwndCurrent == hwndStart, @L); 
} while ChwndCurrent != hwndStart); 
} 


. /* Process other notification codes. */ 


} 


GetDigItem, GetNextDlgTabItem 


HWND GetNextDigTabItem(iwndDlg, hwndCtrl, fPrevious) 
*/ 


Return Value 


Example 


~HWND hwnaDig; /* handle of dialog box 
~HWND hwndCrrl; /* handle of known control ‘af 
BOOL fPrevious; __/* direction flag */ 
The GetNextDlgTabItem function retrieves the handle of the first control that has 
the Meee STOP style that precedes (or follows) the specified control. 
Parameters hwndDlg 
Identifies the dialog box to be eae 
hwndCtrl 


Identifies the control to be used as the starting point for the search. 


fPrevious 
Specifies how the function is to search the dialog box. If this parameter is 
TRUE, the function searches for the previous control in the dialog box. If this 
parameter is FALSE, the function searches for the next control in the dialog 


box. 


The return value is the window handle of the previous (or next) control that has. 


the WS_TABSTOP style, if the function is successful. 


The following example retrieves the handle of the previous control that has the 
WS_TABSTOP style, relative to the control that has the input focus: 
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HWND hdlg; 
HWND hwndControl; 


hwndControl = GetNextDigTabItem(hdlg, GetFocus(), TRUE); 


See Also GetDigItem, GetNextDigGroupItem 


GetNextDriver ie wer fal 


HDRVR GetNextDriver(idrvr, fdwFlag) 
HDRVR hdrvr; /* handle of installable driver */ 
DWORD fdwFlag; _—_—‘/* search flag . */ 


The GetNextDriver function enumerates instances of an installable driver. 


Parameters — _ hdrvr | 

Identifies the installable driver for which instances should be enumerated. This 
parameter must be retrieved by the OpenDriver function. If this parameter is 
NULL, the enumeration begins at either the beginning or end of the list of 
installable drivers (depending on the setting of the flags in the fdwFlag 
parameter). 


fdwFlag 
Specifies whether the function should return a handle identifying only the fitst< 
instance of a driver and whether the function should return handles identifying 
the instances of the driver in the order in which they were loaded. This parame- 
ter can be one or more of the following flags: | : 


Value Meaning 


GND_FIRSTINSTANCEONLY Returns a handle identifying the first instance 
of an installable driver. When this flag is set, 
the function will enumerate only the first in- 
stance of an installable driver, no matter how 
many times the driver has been installed. 


GND_FORWARD | Enumerates subsequent instances of the driver. — 
(Using this flag has the same effect as not 
using the GND_REVERSE flag.) 
GND_REVERSE Enumerates instances of the driver as it was 
| _loaded—each subsequent call to the function — 
returns the handle of the next instance. 


Return Value | The return salted is a instance handle of the installable aver if the function’ is 
successtul. 7 
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GetNextWindow [2x | 


HWND GetNextWindow(hwnd, uFlag) 
HWND hwnd; /* handle of current window */ 
UINT uFlag; /* direction flag =] 


The GetNextWindow function searches for the handle of the next (or previous) 
window in the window manager’s list. The window manager’s list contains entries 
for all top-level windows, their associated child windows, and the child windows 
of any child windows. If the given window is a top-level window, the function. 
searches for the next (or previous) handle of a top-level window. If the given win- 
dow is a child window, the function searches for the handle of the next (or pre- 
vious) child window. 


Parameters hind 
Identifies the current window. 


uF lag 
Specifies whether the function should return a handle to the next window or to 
the previous window. It can be either of the following values: 


Value | Meaning 


GW_HWNDNEXT Returns a handle of the next window. 
GW_HWNDPREV Returns a handle of the previous window. 


Return Value The return value is the handle of the next (or previous) window in the window 
manager’s list if the function is successful. 


See Also GetTopWindow, GetWindow 


GetNumTasks [2x | 


UINT GetNumTasks(void) 


The GetNumTasks function retrieves the number of currently running tasks. 
_ Parameters This function has no parameters. 


Return Value The return value specifies the number of current tasks if the function is successful. 
| Otherwise, it is zero. 


GetObject 
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4] 


int GetObject(hgdiobj, cbBuffer, lpvObject) 


HGDIOBJ hediobj; /* handle of object re | 
int cbBuffer; | /* size of buffer for object information **/ 
void FAR* [pvObject; /* address of buffer for object information */ 


Parameters 


Return Value 


Comments 


Example 


The GetObject function fills a buffer with information that defines a given object. 
The function retrieves a LOGPEN, LOGBRUSH, LOGFONT, or BITMAP 
structure, or an integer, depending on the specified object. 


hgdiobj 

Identifies a logical pen, brush, font, bitmap, or palette: 
cbBuffer 

Specifies the number of bytes to be sonic to the buffer. 


lpvObject 
Points to the buffer that is to receive the information. 


The return value specifies the number of bytes retrieved if the function i is SuCCess- 
ful. Otherwise, it is zero. 


The buffer pointed to by the JpvObject parameter must be sufficiently large to re- 
ceive the information. 


If the hgdiobj parameter identifies a bitmap, the GetObject function returns only 
the width, height, and color format information of the bitmap. The bits can be re- 
trieved by using the GetBitmapBits function. 


If hgdiobj identifies a logical palette, GetObject retrieves an integer that specifies 
the number of entries in the palette; the function does not retrieve the LOG- 


PALETTE structure that defines the palette. To retrieve information about palette 


entries, an application can call the GetPaletteEntries function. 


The following example uses the GetObject function to fill a LOGBRUSH struc- 
ture with the attributes of the current brush and then tests whether the brush style 
is BS_SOLID: 


LOGBRUSH 1b; 
HBRUSH hbr; 


GetObject(hbr, sizeof(LOGBRUSH), (LPSTR) &1b); 
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if (1b.1bStyle == BS SOLID) { 


} 


See Also GetBitmapBits, GetPaletteEntries, GetStockObject 


GetOpenClipboardWindow [aa] 


HWND GetOpenClipboardWindow(void) 
The GetOpenClipboard Window function retrieves the handle of the window that 
currently has the clipboard open. 


Parameters This function has no parameters. 


Return Value The return value is the handle of the window that has the clipboard open, if the 
function is successful. Otherwise, it is NULL. . 


See Also GetClipboardOwner, GetClipboard Viewer, OpenClipboard 


GetOpenFileName : ; aa | 


#include <commdlg.h> 


BOOL GetOpenFileName(/pofn) 
OPENFILENAME FAR? Ipofn; /* address of structure with initialization data = */ 


The GetOpenFileName function creates a system-defined dialog box that makes 
it possible for the user to select a file to open. 


Parameters lpofn 
Points to an OPENFILENAME structure that contains information used to ini- 
tialize the dialog box. When the GetOpenFileName function returns, this struc- 
ture contains information about the user’s file selection. 


_ The OPENFILENAME structure has the following form: 


Return Value 


Errors 
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#tinclude <commdlg.h> 


typedef struct tagOPENFILENAME { /* ofn */ 
DWORD TStructSize; 
HWND hwndOwner; 
HINSTANCE hInstance; 
LPCSTR lpstrFilter; 


LPSTR IpstrCustomFilter; 
DWORD nMaxCustFilter; 
DWORD nFilterIndex; 
LPSTR IpstrFile; 

DWORD nMaxFile; 

LPSTR lpstrFileTitle; 
DWORD nMaxFileTitle; 


LPCSTR IpstrinitialDir; 
LPCSTR IpstrTitle;. 


DWORD - Flags; 
UINT nFileOffset; 
UINT nFileExtension; 


LPCSTR IpstrDefExt; 
LPARAM 1CustData; 
UINT (CALLBACK* IpfnHook) (HWND, UINT, WPARAM, LPARAM); 
LPCSTR lpTemplateName; 
} OPENFILENAME; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if the user selects a file to open. It is zero if an error oc- 
curs, if the user chooses the Cancel button, if the user chooses the Close command 
on the System menu to close the dialog box, or if the buffer identified by the 
IpstrFile member of the OPENFILENAME structure is too small to contain the 
string that specifies the selected file. 


The CommDIgExtendedError function retrieves the error value, which may be © 
one of the following values: | 


CDERR_FINDRESFAILURE 
CDERR_INITIALIZATION 
CDERR_LOCKRESFAILURE 
CDERR_LOADRESFAILURE | 
CDERR_LOADSTRFAILURE - 
CDERR_MEMALLOCFAILURE 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK : 


Ata GetOpenFileName 


Comments 


Example 


CDERR_NOTEMPLATE 


~CDERR_STRUCTSIZE 


FNERR_BUFFERTOOSMALL 
FNERR_INVALIDFILENAME 
FNERR_SUBCLASSFAILURE 


If the hook function (to which the IpfnHook member of the OPENFILENAME 


structure points) processes the WM_CTLCOLOR message, this function must re- 
turn a handle of the brush that should be used to paint the control background. 


The following example copies file-filter strings into a buffer, initializes an OPEN- 
FILENAME structure, and then creates an Open dialog box. 


The file-filter strings are stored in the resource file in the following form: 


STRINGTABLE 
BEGIN 

IDS_FILTERSTRING "Write Files(*.WRI)|*.wri|Word Files(*.DOC)|*.doc|" 
END | 


The replaceable character at the end of the string is used to break the entire string 
into separate strings, while still guaranteeing that all the strings are continguous in 
memory. 


OPENFILENAME ofn; 

char szDirName[256]; 

char szFile[256], szFileTitle[256]; 

UINT i, cbString; 

char chReplace; /* string separator for szFilter */ 
char szFilter[256]; 

HFILE hf; 


/* Get the system directory name and store in szDirName */ 


GetSystemDirectory(szDirName, sizeof(szDirName)); 
szFile[Q@] = '\Q'; ? 


if ((cbString = LoadString(hinst, IDS_FILTERSTRING, 
szFilter, sizeof(szFilter))) == 0) { 
ErrorHandler(); 
return OL; 
} | 
chReplace = szFilter[cbString - 1]; /* retrieve wild character */ 


for (i = 0; szFilter[i] != '\O'; i++) {. 
if (szFilter[i] == chReplace) 
szFilter[Li] = '\@'; 
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/* Set all Structure members to zero. */ 
memset(&ofn, @, sizeof(OPENFILENAME) ); 


ofn.1StructSize = sizeof(OPENFILENAME) ; 

ofn.hwndOwner = hwnd; 

ofn.IpstrFilter = szFilter; 

ofn.nFilterIndex = 1; 

ofn.IpstrFile= szFile; 

ofn.nMaxFile = sizeof(szFile); 

ofn.IpstrFileTitle = szFileTitle; 

ofn.nMaxFileTitle = sizeof(szFileTitle); 

ofn.IpstrInitialDir = szDirName; 

ofn.Flags = OFN_SHOWHELP | OFN_PATHMUSTEXIST OFN_ FILEMUSTEXIST; 


if (GetOpenFileName(&ofn)) { 
hf = _lopen(ofn.IpstrFile, OF_READ); 


. /* Perform file operations */ 


} 
else | 
ErrorHandler(); 


See Also GetSaveFileName | 


GetOutlineTextMetrics faa] 


WORD GetOutlineTextMetrics(hdc, cbData, lpotm) 


HDC hdc; /* handle of device context a 
UINT cbData; : /* size of buffer for information */ 
OUTLINETEXTMETRIC FAR® lpotm; /* address of structure for metrics */ 
The GetOutlineTextMetrics muncnon retrieves metric information for TrueType 
fonts. | : , 
Parameters hdc 
Identifies the device context. 
cbData 
Specifies the size, in bytes, of the buffer to which information is returned. 
lpotm 


Points to an OUTLINETEXTMETRIC structure. If this parameter is NULL, 
the function returns the size of the buffer required for the retrieved metric infor- 
_ Ination. The OUTLINETEXTMETRIC structure has the following form: 
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Return Value 


Comments 


See Also 


typedef struct tagOUTLINETEXTMETRIC { 


UINT 
_ TEXTMETRIC 

BYTE 
PANOSE 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
INT 
INT 
UINT 
UINT 
UINT 
RECT 
INT 
INT 
UINT 
UINT 
POINT 
POINT 
POINT 
POINT 
UINT 
INT: 
INT 
UINT 
PSTR 
PSTR 
PSTR 
PSTR 


otmSize; 
otmTextMetrics; 
otmFiller; 
otmPanoseNumber; 
otmfsSelection; 
otmfsType; 


otmsCharSlopeRise; 


otmsCharS1lopeRun; 
otmItalicAngle; 
otmEMSquare; 
otmAscent; 
otmDescent; 
otmLineGap; 
otmsXHeight; 
otmsCapEmHeight; 


‘otmrcFontBox; 


otmMacAscent; 
otmMacDescent; 
otmMacLineGap; 
otmusMinimumPPEM; 
otmptSubscriptSize; 
otmptSubscriptOffset; 
otmptSuperscriptSize; 
otmptSuperscriptOffset; 
otmsStrikeoutSize; 
otmsStrikeoutPosition; 
otmsUnderscorePosition; 
otmsUnderscoreSize; 
otmpFamilyName; 
otmpFaceName; 
otmpStyleName; 
otmpFul]Name; 


} OUTLINETEXTMETRIC; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The OUTLINETEXTMETRIC structure contains most of the font metric infor- 
mation provided with the TrueType format, including a TEXTMETRIC struc- 
ture. The last four members of the OUTLINETEXTMETRIC structure are 
pointers to strings. Applications should allocate space for these strings in addition 


_ to the space required for the other members. Because there is no system-imposed 
limit to the size of the strings, the simplest method for allocating memory is to re- 


trieve the required size by specifying NULL for the /potm parameter in the first 
call to the GetOutlineTextMetrics function. oe 


GetTextMetrics 
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GetPaletteEntries a 


UINT GetPaletteEntries(hpal, iStart, cEntries, Ippe) 


HPALETTE hpai; /* handle of palette */ 
UINT iStart; /* first palette entry to retrieve 7), 
UINT cEntries; /* number of entries to retrieve a 
PALETTEENTRY FAR? [ppe; /* address of structure for palette entries 7) 
The GetPaletteEntries function retrieves a range of palette entries in a logical. 
palette. 
Parameters hpal 


‘Return Value 


See Also 


Identifies the logical palette. 


iStart 


Specifies the first logical-palette entry to ibe retrieved. 


cEntries 


Specifies the number of logical-palette entries to be retrieved. 


Ippe 


Points to an array of PALETTEENTRY structures that will receive the palette 
entries. The array must contain at least as many structures as specified by the 
cEntries parameter. The PALETTEENTRY structure has the following form: 


typedef struct tagPALETTEENTRY { /* pe */ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the number of entries retrieved from the logical Bale if the 
function is successful. Otherwise, it is zero. | 


GetSystemPaletteEntries 
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GetParent 3 [2x | 


HWND GetParent(hwnd) 
HWND hwnd; /* handle of window =f 


The GetParent function retrieves the handle of the given window’s parent win- 
dow (if any). 


Parameters hwnd 
Identifies the window whose parent window handle is to be retrieved. 


Return Value The return value is the handle of the parent window if the function is successful. 
Otherwise, it is NULL, indicating an error or no parent window. 


See Also SetParent 


GetPixel _ 47) a 


COLORREF GetPixel(hdc, nXPos, nYPos) 


HDC hdc; /* handle of device context oF 
int nXPos; _—/* x-coordinate of pixel to retrieve */ 
int nYPos; /* y-coordinate of pixel to retrieve sf 


The GetPixel function retrieves the RGB (red, green, blue) color value of the pixel 
at the specified coordinates. The pemt must be in the clipping region; if itis not, 
the function is ignored. 


Parameters hdc 
Identifies the device context. 


nXPos 
Specifies the logical x-coordinate of the point to be examined. 


nYPos 
Specifies the logical y-coordinate of the point to be examined. 


Return Value The return value specifies an RGB color value for the color of the given point, if 
the function is successful. It is —1 if the coordinates do not specify a point in the 
clipping region. 


Comments Not all devices support the GetPixel function. For more information, see the de- 
, scription of the GetDeviceCaps function. 
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See Also GetDeviceCaps, SetPixel 


GetPolyFillMode ra 


int GetPolyFillMode(hdc) 
HDC hdc; /* handle of device context =) 


The GetPolyFillMode function retrieves the current polygon filling mode. 


Parameters hd 
Identifies the device context. 


Return Value The return value specifies the polygon-filling mode, ALTERNATE or WINDING, 
if the function is successful. 


Comments When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and | 
fourth side, and so on. | 7 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
ina polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, a count is incremented. When the line 
passes through a counterclockwise line segment, the count is decremented. The 
area 1s filled if the count is nonzero when the line reaches the outside of the figure. 


Example The following example uses the GetPolyFillMode function to determine whether 
: | the current polygon-filling mode is ALTERNATE: _ 


int nPolyFil1Mode; 


nPolyFillMode = GetPolyFillMode(hdc); 
if (mPolyFillMode == ALTERNATE) { 


} 


SeeAlso —S—«SSet Poly FillMode 
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GetPriorityClipboardFormat — 


int GetPriorityClipboardFormat([puPriorityList, cEntries) 
UINT FAR®* [puPriorityList; /* address of priority list if 
int cEntries; /* count of entries in list */ 


The GetPriorityClipboardFormat function retrieves the first clipboard format in 
a list for which data exists in the clipboard. 


Parameters _[puPriorityList | 
Points to an integer array that contains a list of clipboard formats in priority - 
order. For a description of the data formats, see the BescHpHon of the a : 
ClipboardData function. 


cEntries 
Specifies the number of entries in the priority list. This value must not be 
greater than the number of entries in the list. 


Return Value The return value is the highest priority clipboard format in the list for which data 
exists. If no data exists in the clipboard, the return value is NULL. If data exists in 
the clipboard that does not match any format in the list, the return value is —1. 

See Also CountClipboardFormats, EnumClipboardFormats, GetClipboardFormat- 


Name, IsClipboardFormatAvailable, ee eee eee 
SetClipboardData 
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UINT GetPrivateProfileInt(/pszSection, IpszEntry, default, IpszF. may 


LPCSTR IpszSection; /* address of section 

LPCSTR IpszEntry; /* address of entry y 
int default; /* return value if entry not found | 
LPCSTR [pszFilename; /* address of initialization filename ] 


The GetPrivateProfileInt function retrieves the value of an integer from an entry 
within a specified section of a specified initialization file. 


Parameters [pszSection 
Points to a null-terminated string containing the section heading 1 in the initializa- 
tion file. 


Return Value 


Comments 
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lpszEntry 
Points to the null-terminated string sontainiae the entry whose value is to be re- 
trieved. 


default 
Specifies the default value to return if the entry cannot be found in the initializa- 
tion file. This value must be a positive integer in the range 0 through 32,767 | 
(Ox0000 through Ox7FFF). 


lpszFilename 
Points to a null-terminated string that names the initialization file. If this pa- 
rameter does not contain a full path, Windows searches for the file in the Win- 
_ dows directory. 


The return value is the integer value of the specified entry if the function is 


~ successful. It is the value of the default parameter if the function does not find the 


entry. The return value is zero if the value that corresponds to the specified entry is 
not an integer. 


The function searches the file for an entry that matches the name specified by the 
IpszEntry parameter under the section heading specified by the /pszSection parame- 
ter. An integer entry in the initialization file must have the following form: 7 


[section] 
entry=value 


If the value that corresponds to the entry consists of digits followed by non- 
numeric characters, the function returns the value of the digits. For example, the 
function would return 102 for the line “Entry=102abc”’. | 


The GetPrivateProfileInt function is not case-dependent, so the strings in the — 


lpszSection and [pszEntry parameters may contain a combination of uppercase and 
lowercase letters. 


_GetPrivateProfileInt supports hexadecimal notation. When GetPrivate- 
~ ProfileInt is used to retrieve a negative integer, the value should be cast to an int. 


An application can use the GetProfileInt function to retrieve an integer value 
_ from the WIN.INI file. | 
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Example | The following example uses the GetPrivateProfileInt function to retrieve the 
last line number by reading the LastLine entry from the [MyApp] section of 
TESTCODE.INI: 


WORD wint; 
char szMsg[144]; 


wInt = GetPrivateProfileInt("MyApp", “LastLine”, 
0, “testcode.ini"); 


sprintf(szMsg, “last line was %d", wiInt); | 
MessageBox(hwnd, szMsg, "GetPrivateProfileInt", MB_OK); 


See Also GetPrivateProfileString, GetProfileInt 


GetPrivateProfileString 


int GetPrivateProfileString(/pszSection, lpszEntry, lpszDefault, IlpszReturnBuffer, cbReturnBuffer, 


lpszFilename) 

LPCSTR IpszSection; /* address of section **/ 

LPCSTR IpszEntry; /* address of entry a 

LPCSTR IpszDefault; /* address of default string © sf 

LPSTR IpszReturnBuffer; /* address of destination buffer */ 

int cbReturnBuffer; /* size of destination buffer **/ 

LPCSTR [pszFilename; /* address of initialization filename **/ 
The GetPrivateProfileString function retrieves a character string from the 
specified section in the specified initialization file. | 

Parameters IpszSection 


Points to a null-terminated string that specifies the section containing the entry. 


lpszEntry | 
Points to the null-terminated string containing the entry whose associated string 
is to be retrieved. If this value is NULL, all entries in the section specified by 
the [pszSection parameter are copied to the buffer specified by the /pszReturn- 
Buffer parameter. For more information, see the following Comments section. 


lpszDefault | 
Points to a null-terminated string that specifies the default value for the given 
entry if the entry cannot be found in the initialization file. This parameter must 
never be NULL. 


Return Value 


Comments 
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[pszReturnBuffer 
Points to the buffer that receives the character string. 


cbReturnBuffer 
Specifies the size, in bytes, of the oe pointed to by the IpszReturnBuffer pa- 
rameter. 


[pszFilename 
Points to a null-terminated string that names the initialization file. If this pa- 
rameter does not contain a full path, Windows searches for the file in the Win- 
dows directory. | 


The return value specifies the number of bytes ike to the specified buffer, not 
including the terminating null character. 


The function searches the file for an entry that matches the name specified by the 
[pszEntry parameter under the section heading specified by the lpszSection parame- 
ter. If the entry is found, its corresponding string is copied to the buffer. If the — 
entry does not exist, the default character string specified by the IpszDefault pa- 
rameter is copied. A string entry in the initialization file must have the torowe | 


form: 


[section] 
entry=string 


If lpszEntry is NULL, the GetPrivateProfileString function copies all entries in — 
the specified section to the supplied buffer. Each string will be null-terminated, 
with the final string ending with two zero-termination characters. If the supplied 
destination buffer is too small to hold all the strings, the last string will be trun- 
cated and followed with two zero-termination characters. 


If the string associated with IpszEntry is enclosed in single or double quotation — 
marks, the marks are discarded when GetPrivateProfileString returns the string. 


GetPrivateProfileString is not case-dependent, so the strings in IpszSection and 


: ipszEntry may contain a combination of uppercase and lowercase letters. 


An application can use the GetProfileString function to retrieve a sirmg from the 


WIN.INI file. 


_ The IpszDefault parameter must point toa valid string, even ‘if the string is empty _ 


(its first character 1 iS Zet0). 
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Example The following example uses the GetPrivateProfileString function to determine 
the last file saved by the [MyApp] application by reading the LastFile entry in 
TESTCODE.INI: | 


char szMsg[144], szBuf[80]; 


GetPrivateProfileString("MyApp", “LastFile”, 
""  szBuf, sizeof(szBuf), "testcode.ini"™); 


sprintf(szMsg, "last file was mS", SzBuf); 
MessageBox(hwnd, szMsg, "GetPrivateProfileString", MB_OK); 


See Also GetProfileString, WritePrivateProfileString 


GetProcAddress ax] 


FARPROC GetProcAddress(hinst, IpszProcName) 
HINSTANCE hinst; /* handle of module */ 
LPCSTR IpszProcName; /* address of function */ 


The GetProcAddress function retrieves the address of the given module function. 


Parameters hinst 
Identifies the module that contains the function. 


lpszProcName 
Points to a null-terminated string containing the function name, or specifies the 
ordinal value of the function. If it is an ordinal value, the value must be in the 
low-order word and the high-order word must be zero. 


Return Value The return value is the address of the module function’s entry point if the 
_ GetProcAddress function is successful. Otherwise, it is NULL. 


If the IpszProcName parameter is an ordinal value and a function with the 
specified ordinal does not exist in the module, GetProcAddress can still return a 
non-NULL value. In cases where the function may not exist, specify the function — 
by name rather than ordinal value. 


Comments — Use the GetProcAddress function to retrieve addresses of exported functions in 
dynamic-link libraries (DLLs). The MakeProclInstance function can be used to 
access functions within different instances of the current module. - 
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The spelling of the function name (pointed to by the IpszProcName parameter) 
must be identical to the spelling as it appears in the EXPORTS section of the 
source DLL’s module deumuen (.DEF) file. 


Example The following example uses the GetProcAddress function to retrieve the address 
of the TimerCount function in TOOLHELP.DLL: 


char szBuf{8Q]; 

TIMERINFO timerinfo; 

HINSTANCE hinstToolHelp; 

BOOL (FAR *IpfnTimerCount) (TIMERINFO FAR*); 

/* Turn off the "File not found" error box. */ 
SetErrorMode(SEM_NOOPENFILEERRORBOX) ; 

/* Load the TOOLHELP.DLL library module. */ 

hinstToolHelp = LoadLibrary("TOOLHELP.DLL"); 

if (hinstToolHelp > HINSTANCE_ERROR) { /* loaded successfully */ 


/* Retrieve the address of the TimerCount function. */ 


(FARPROC) IpfnTimerCount = 
GetProcAddress(hinstToolHelp, “TimerCount"); 


if (1pfnTimerCount != NULL) { 
/* Call the TimerCount function. */ 
timerinfo.dwSize = sizeof(TIMERINFO); 
if ((#1pfnTimerCount) ((TIMERINFO FAR *) &timerinfo)) 
sprintf(szBuf, “task: %4lu seconds\nVM: %lu seconds”, 


timerinfo.dwmsSinceStart / 1000, 
timerinfo.dwmsThisVM / 1000); 


i 
else { : 
strcpy(szBuf, "“TimerCount failed"); 
as ne 
j 
“else { | | | | 

strcpy(szBuf, "GetProcAddress failed"); 

} | | oo ee 


. /* Free the TOOLHELP. DLL Hees module. */ 


"FreeLibrary(hinstToolHe1p) 
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else { | 
strcpy(szBuf, “LoadLibrary failed"); 
, | | 


MessageBox(NULL, szBuf, "Library Functions", MB_ICONHAND); 


See Also MakeProclInstance 


GetProfilelnt [2x | 


UINT GetProfileInt(/pszSection, IpszEntry, default) 


LPCSTR [pszSection; /* address of section *k/ 
LPCSTR /pszEntry; /* address of entry */ 
int default; /* return value if entry is not found a 


The GetProfileInt function retrieves the value of an integer from an entry within a 
specified section of the WIN.INI initialization file. | 


Parameters IpszSection 
| Points to a null-terminated string that specifies the section containing the entry. 


lpszEntry © 
Points to the null-terminated string containing the entry whose value is to be re- 
trieved. 


default 
Specifies the default value to return if the entry cannot be found. This value can 
be an unsigned value in the range 0 through 65,536 or a signed value in the 
range —32,768 through 32,768. Hexadecimal notation is accepted for both posi- 
tive and negative values. | 


Return Value The return value is the integer value of the string following the specified entry, if 
the function is successful. The return value is the value of the default parameter if 
the function does not find the entry. The return value is zero if the value that corre- 
sponds to the specified entry is not an integer. 


Comments | The GetProfileInt function is not case-dependent, so the strings in the /pszSection 
and /pszEntry parameters may contain a combination of uppercase and lowercase 
letters. — | 


GetProfileInt supports hexadecimal notation. When the function is used to re- 
trieve a negative integer, the value should be cast to an int. 


An integer entry in the WIN.INI file must have the following form: 


Example 


See Also 


GetProfileString 
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[section] 
entry=value— 


If the value that corresponds to the entry consists of digits followed by non- 
numeric characters, the function returns the value of the digits. For example, the 
function would return 102 for the line “Entry=102abc”. 


An application can use the GetPrivateProfileInt function to retrieve an integer 
from a specified file. 


The following example uses the GetProfileInt function to retrieve the screen-save 
timeout time from the WIN.INI file: 


WORD wlimeOut; 
char szMsg[8]; 


wlimeQut = GetProfileInt("windows", 
"ScreenSavelimeOut", 0); 


sprintf(szMsg, "timeout time is %d", wlimeQut); 
MessageBox(hwnd, szMsg, "GetProfileInt", MB_OK); 


GetPrivateProfileInt, GetProfileString - 


int GetProfileString(/pszSection, lpszEntry, IpszDefault, Peter en cbReturnBuffer) 


LPCSTR IpszSection; /* address of section 
LPCSTR IpszEntry; /* address of entry ¥ 
LPCSTR IpszDefault; /* address of default string Cee 


LPSTR [pszReturnBuffer; /* address of destination buffer */ 


int cbReturnBuffer; 


Parameters 


/* size of destination buffer */ 


The GetProfileString function retrieves the string associated with an entry within 
the specitied section in the WIN.INI initialization file. 


peiseciion | 
Points to a null- terminated string that specifies the section containing the entry. 


IpszEntry 7 | 
Points to the null-terminated string containing the entry whose associated string 
is to be retrieved. If this value is NULL, all entries in the section specified by 
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Return Value 


| Comments 


Example 


the IpszSection parameter are copied to the buffer specified by the lpszReturn- 
Buffer parameter. For more information, see the following Comments section. 


lpszDefault 
Points to the default value for the given entry if the entry cannot be found in the 
initialization file. This parameter must never be NULL. 


[pszReturnBuffer 
Points to the buffer that will receive the character string. 


cbReturnBuffer 
Specifies the size, in bytes, of the buffer pointed to by the lpszReturnBuffer pa- 
rameter. 


The return value is the number of bytes copied to the buffer, not including the ter- 
minating zero, if the function is successful. 


If the [pszEntry parameter is NULL, the GetProfileString function copies all en- 
tries in the specified section to the supplied buffer. Each string will be null-termi- 
nated, with the final string terminating with two null characters. If the supplied 
destination buffer is too small to hold all the strings, the last string will be trun- 
cated and followed by two terminating null characters. 


If the string associated with IpszEntry is enclosed in single or double quotation 


_ marks, the marks are discarded when GetProfileString returns the string. — 


GetProfileString is not case- dependent, so the strings in the JpszSection and 
[pszEntry parameters may contain a combination of uppercase and lowercase let- 
ters. 


A string entry in the WIN.INI file must have the following form: 


[section| 
entry=string 


An application can use the GetPrivateProfileString function to retrieve a a sting 
from a specified file. 


The [pszDefault parameter must point to a valid string, even if the string is empty 
(its first character is zero). | 


The following isle uses the GetProfileString function to list all the entries 
and strings in the [windows] section of the WIN.INI file: 


See Also 


GetProp 


int c, cc; 

PSTR pszBuf, pszKey; 

char szMsg[80], szVal[8@]; 

/* Allocate a buffer for the entries. */ 

pszBuf = (PSTR) LocalAlloc(LMEM_FIXED, 1024); 

/* Retrieve all the entries in the [windows] section. */ 
GetProfileString("windows", NULL, "", pszBuf, 1024); 


* Retrieve the string for each entry, until 
* reaching the double null character. 


for (pszKey = pszBuf, c = Q@; 
*pszKey != '\@'; pszKey += strlen(pszKey) + 1) { 
/* Retrieve the value for each entry in the buffer. */ 


GetProfileString("windows", pszKey, “not found", 
szVal, sizeof(szVal)); 


cc = sprintf(szMsg, "%s = 4S", pszkey, szVal); 
TextOut(hdc, 10, 15 * c++, szMsg, cc); 
} | Beng 


LocalFree((HANDLE) pszBuf); 


GetPrivateProfileString, WriteProfileString 
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GetProp 


~ HANDLE GetProp(hwnd, Ipsz) | 


HWND hwnd; 
LPCSTR Ipsz; 


Parameters 


/* handle of window */ 
/* atom or address of string */ 


[ 2.x | 


The GetProp function retrieves a data handle from the property list of a window. 
The character string pointed to by the /psz parameter identifies the handle to be re- 
trieved. The string and handle must be added to the property list by a previous call 


to the SetProp function. 


hwnd 7 , : | 
Identifies the window whose property list is to be searched. 
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lpsz | 

Points to a null-terminated string or an atom that identifies a string. If an atom 
is given, it must be a global atom created by a previous call to the GlobalAdd- 
Atom function. The atom, a 16-bit value, must be placed in the low-order word 
of the as parameter; the high-order word must be zero. 


Return Value The return value is the associated data handle if the property list contains the given 
string. Otherwise, it is NULL. 


Comments The value retrieved by the GetProp function can be any 16-bit value useful to the 
application. 
See Also GlobalAddAtom, RemoveProp, SetProp 


GetQueueStatus a Eu 


DWORD GetQueueStatus(fuFlags) 
UINT fuFlags; /* queue-status flags = */ 


The GetQueueStatus function returns a value that indicates the e type of messages 
in the queue. 


This function is very fast and is typically used inside speed-critical loops to deter- 
mine whether the GetMessage or PeekMessage function should be called to 
process input. : 


GetQueueStatus returns two sets of information: whether any new messages have 
been added to the queue since GetQueueStatus, GetMessage, or PeekMessage 
was last called, and what kinds of events are currently in the queue. 


Parameters — fuFlags 
Specifies the queue-status flags to be retrieved. This parameter can be a combi- 
nation of the following values: 


Value _ Meaning | 

QS_KEY _ WM_CHAR message is in the queue. 

QS_MOUSE -WM_MOUSEMOVE or WM_*BUTTON* message is 
3 - inthe queue. 

QS_MOUSEMOVE WM_MOUSEMOVE message is in the queue. 


QS_MOUSEBUTTON WM_*BUTTON* message is in the queue. 
QS_PAINT | WM_PAINT message is in the queue. 
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Value Meaning 
QS_POSTMESSAGE Posted message other than those listed above is in the 
queue. , 
QS_SENDMESSAGE Message sent by another application is in the queue. 
QS_TIMER | WM_TIMER message is in the queue. 
Return Value _ The high-order word of the return value indicates the types of messages currently 


in the queue. The low-order word shows the types of messages added to the queue 
and are still in the queue since the last call to the GetQueueStatus, GetMessage, 
or PeekMessage function. 


Comments The existence of a QS_ flag in the return value does not guarantee that a sub- 

7 sequent call to the PeekMessage or GetMessage function will return a message. 
GetMessage and Peek Message perform some internal filtering computation that 
may cause the message to be processed internally. For this reason, the return 
value from GetQueueStatus should be considered only a hint as to whether 
GetMessage or PeekMessage should be called. 


See Also — GetInputState, GetMessage, Peek Message 


GetRasterizerCaps : [Bal 


BOOL GetRasterizerCaps(ipraststat, cb) 
RASTERIZER_STATUS FAR? [praststat; /* address of structure for status */ 
int cb; /* number of bytes in structure */ 


The GetRasterizerCaps function returns flags indicating whether TrueType fonts 
are installed in the system. 


Parameters Ipraststat | : | 
: Points to a RASTERIZER_ STATUS structure that receives information about 
_ the rasterizer. The RASTERIZER_STATUS structure has the following form: 


typedef struct tagRASTERIZER_STATUS { /* rs */ 
int nSize; | 
int wFlags; 
int nLanguagelID; 

} RASTERIZER_STATUS; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
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cb 
Specifies the number of bytes that will be copied into the structure pointed to 
by the lpraststat parameter. 


- Return Value 7 The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The GetRasterizerCaps function enables applications and printer drivers to deter- 
| mine whether TrueType is installed. 


If the TT_AVAILABLE flag is set in the wF lags member of the 
RASTERIZER_STATUS structure, at least one TrueType font is installed. 
If the TT_ENABLED flag is set, TrueType is enabled for the system. 


See Also GetOutlineTextMetrics 


GetRgnBox 


int GetRenBox(hrgn, Iprc) 
HRGN hrgn; /* handle of region i 
RECT FAR® (prc; /* address of structure with rectangle */ 


The GetRgnBox function retrieves the coordinates of the bounding rectangle of 
the given region. 


Parameters | hrgn 
Identifies the region. 


lpre 
Points to a RECT structure that receives the coordinates of the bounding 
rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is SIMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR. — 


Example 


GetROP2 


int GetROP2(hdc) 
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The following example uses the GetRgnBox function to determine the type of a 
region: 


RECT rc; 
HRGN hrgn; 
int RgnType; 


RgnType = GetRgnBox(hrgn, &rc); 


if (RgnType == COMPLEXREGION) 

TextOut(hdc, 10, 10, "COMPLEXREGION", 13); 
else if (RgnType == SIMPLEREGION) 

TextOut(hdc, 10, 10, "SIMPLEREGION", 12); 
else 

TextOut(hdc, 10, 10, "NULLREGION", 10); 


Lex] 


HDC hdc; /* handle of device context */ 


Parameters 


Return Value 


Comments 


The GetROP2 function retrieves the current drawing mode. The drawing mode 
specifies how the colors of the pen and the interior of filled objects are combined 
with the color already on the screen surface. 


hdc 
Identifies the device context. 


The return value specifies the drawing mode if the function is successful. 


The drdwing mode is for raster devices only and does not apply to vector devices. 
It can be any of the following values: | 


‘Value Meaning 
R2_BLACK Pixel is always black. 
R2_WHITE Pixel is always white. 
R2_NOP Pixel remains unchanged. 
R2_NOT - Pixel is the inverse of the screen color. 
~R2_COPYPEN Pixel is the pen color. 
R2_NOTCOPYPEN Pixel is the inverse of the pen color. 


R2_MERGEPENNOT Pixel is a combination of the pen color and the inverse of 
| the screen color (final pixel = (~screen pixel) | pen). 
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Example 


See Also 
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Value 


R2_MASKPENNOT 


R2_MERGENOTPEN 


R2_MASKNOTPEN 


RO. MERGEPEN 

R2_ NOTMERGEPEN 
R2_ MASKPEN 

R2_ NOTMASKPEN 


R2_XORPEN 


R2_NOTXORPEN 


Meaning 


Pixel is a combination of the colors common to both the pen 
and the inverse of the screen (final pixel = (~screen pixel) & 
pen). 

Pixel is a combination of the screen color and the inverse of 
the pen color (final pixel = (~pen) | screen pixel). 

Pixel is a combination of the colors common to both the 
screen and the inverse of the pen (final pixel = (~pen) & 
screen pixel). 

Pixel is a combination of the pen color and the screen color 
(final pixel = pen | screen pixel). 

Pixel is the inverse of the R2 MERGEPEN color (final 
pixel = ~(pen | screen pixel)). 

Pixel is a combination of the colors common to both the pen 
and the screen (final pixel = pen & screen pixel). 

Pixel is the inverse of the R2_MASKPEN color (final pixel 
= ~(pen & screen pixel)). 

Pixel is a combination of the colors that are in the pen and 
in the screen, but not in both (final pixel = pen “ screen 
pixel). - < 

Pixel is the inverse of the R2_XORPEN color (final pixel = 
~(pen “ screen pixel)). 


The following example uses the GetROP2 function to test whether the current 
drawing mode is R2_COPYPEN: | 


int nROP; 


nROP = GetROP2(hdc); 


1f (nROP == R2_COPYPEN) ee | 
TextOut(hdc, 100, 100, "ROP is R2_COPYPEN.", 18); 


GetDeviceCaps, SetROP2 


GetSaveFileName 


#include <commdlg.h> 


BOOL GetSaveFileName(/pojn) 


{ 
Wee 
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[ 3.1 | 


OPENFILENAME FAR?® Ipofn; /* address of structure with initialization data ra 


The GetSaveFileName function creates a system-defined dialog box that makes it 
possible for the user to select a file to save. 


Parameters | Ipofn 


Points to an OPENFILENAME structure that contains information used to ini- 
tialize the dialog box. When the GetSaveFileName function returns, this struc- 
ture contains information about the user’s file selection. 


The OPENFILENAME structure has the following form: 


#Hinclude <commdlg.h> 


typedef struct tagOPENFILENAME { /* ofn */ 


DWORD 
HWND 
HINSTANCE 
LPCSTR 
LPSTR 
DWORD 
DWORD 
LPSTR 
DWORD 
LPSTR 
DWORD 
LPCSTR 
LPCSTR 
DWORD 


} OPENFILENAME; 


1StructSize; 
hwndOwner; 
hInstance; 
lpstrFilter; 
IpstrCustomFilter; 
nMaxCustFilter; 
nFilterIndex; 
IpstrFile; 
nMaxFile; 
IpstrFileTitle; 
nMaxFileTitle; 
IpstriInitialDir; 
IpstrTitle; 
Flags; 
nFileOffset; 


~nFileExtension; 


IpstrDefExt; | - 
1CustData; , 
(CALLBACK* IpfnHook) (HWND, UINT, WPARAM, LPARAM) ; 
IpTemplateName; 


For a full description of this structure, see ve M icrosoft Windows Program- 
mer’s Pere, Volume 3. | 


Return Value — The aa value is nonzero if the user selects a file to save. It is zero if an error oc- 
| | curs, if the user clicks the Cancel button, if the user chooses the Close command 
_on the System menu to close the dialog box, or if the buffer identified by the 
IpstrFile member of the OPENFILENAME structure is too small to contain the 
string that specifies the selected file. 


os 
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Errors 


Comments 


Example 


The CommDIgExtendedError retrieves the error value, which may be one of the 
following values: 


CDERR_FINDRESFAILURE 
CDERR_INITIALIZATION 
CDERR_LOCKRESFAILURE 
CDERR_LOADRESFAILURE 
CDERR_LOADSTRFAILURE 
CDERR_MEMALLOCFAILURE 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK 
CDERR_NOTEMPLATE 
CDERR_STRUCTSIZE 
FNERR_BUFFERTOOSMALL 
FNERR_INVALIDFILENAME 
FNERR_SUBCLASSFAILURE 


If the hook function (to which the IpfnHook member of the OPENFILENAME 
structure points) processes the WM_CTLCOLOR message, this function must re- 
turn a handle for the brush that should be used to paint the control background. 


The following example copies file-filter strings (filename extensions) into a buff- 
er, initializes an OPENFILENAME structure, and then creates a Save As dialog 
box. 


The file-filter strings are stored in the resource file in the following form: 


STRINGTABLE 

BEGIN 

IDS_FILTERSTRING "Write Files(*.WRI)|*.wri|Word Files(*.DOC)|*.doc|" 
END | 


The replaceable character at the end of the string is used to break the entire string 
into separate strings, while still guaranteeing that all the strings are continguous in 
memory. 


OPENFILENAME ofn; 

char szDirName[256]; 

char szFile[256], szFileTitle[256]; 

UINT i, cbString; 

char chReplace; /* string separator for szFilter */ 
char szFilter[256]; 


HFILE hf; 


/* : : 
* Retrieve the system directory name and store it in 
* szDirName. 
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* / 
GetSystemDirectory(szDirName, sizeof(szDirName) ); 


if ((cbString = LoadString(hinst, IDS _FILTERSTRING, 
szFilter, sizeof(szFilter))) == 0) { 
ErrorHandler(); 
return @Q; 


} 
-chReplace = szFilter[cbString - 1]; /* retrieve wild character */ 


for (i = 0; szFilterLi] != '\@'; i++) { 
if (szFilter[i] == chReplace) 
szFilterLi] = '\@'; 
} 


/* Set all structure members to zero. */ 
memset(&ofn, 0, sizeof(OPENFILENAME)); 

/* Initialize the OPENFILENAME members. */ 
szFilel@] = *\@'; 


ofn.1StructSize = sizeof(OPENFILENAME) ; 
-ofn.hwndOwner = hwnd; 

ofn.IpstrFilter = szFilter;. | 

ofn.lpstrFile= szFile; 

ofn.nMaxFile = sizeof(szFile); 

ofn.lpstrFileTitle = szFileTitle; © 

ofn.nMaxFileTitle = sizeof(szFileTitle); 

ofn.IpstrinitialDir = szDirName; 

ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT ; 


if (GetSaveFileName(&ofn)) { 
. /* Perform file operations. */ 
} 


else 
ErrorHandler(); 


‘See Also GetOpenFileName 
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GetScrollPos ee Rx] 


int GetScrollPos(hwnd, fnBar) | 
HWND hwnd; /* handle of window with scroll bar +] 
int fnBar; /* scroll bar flags | sa 


The GetScrollPos function retrieves the current position of the scroll box (thumb) 
of a scroll bar. The current position is a relative value that depends on the current 
scrolling range. For example, if the scrolling range is 0 through 100 and the scroll 
box is in the middle of the bar, the current position is 50. 


Parameters hwnd 3 
| Identifies a window that has standard scroll bars or a scroll bar control, depend- 
ing on the value of the fnBar parameter. 


jnBar 
Specifies the scroll bar to examine. It can be one of the following values: 


Value Meaning 


SB_CTL Retrieves the position of a scroll bar control. In this case, the hwnd 

parameter must be the window handle of a scroll bar control. 
SB_HORZ __ Retrieves the position of a window’s horizontal scroll bar. 
SB_VERT Retrieves the position of a window’s vertical scroll bar. 


Return Value The return value specifies the current position of the scroll box in the scroll bar, if 
the function is successful. Otherwise, it is zero, indicating that the hwnd parameter 
1s invalid or that the window does not have a scroll bar. 


See Also GetScrollRange, SetScrollPos, SetScrollRange 


GetScrollRange a] 


void GetScrollRange(hwnd, jnBar, lpnMinPos, lpnMaxPos) 3 
HWND hwnd; /* handle of window with scroll bar = 


int fnBar; /* scroll bar flags */ 
int FAR* [pnMinPos; /* receives minimum position | 
int FAR* [pnMaxPos; /* receives maximum position i 


The GetScrollRange function retrieves the current minimum and maximum scroll 
bar positions for the given scroll bar. 
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Parameters hwnd 
Identifies a window that has standard cil baits or ascroll bar control, depend- 
ing on the value of the fnBar parameter. 


jnBar 
Specifies which scroll bar to retrieve. This parameter can be one of the follow- 
ing values: | 
Value Meaning 
SB_CTL Retrieves the position of a scroll bar control; in this case, the hwnd | 


parameter must be the handle of a scroll bar control. 
SB_HORZ Retrieves the position of a window’s horizontal scroll bar. 
SB_VERT Retrieves the position of a window’s vertical scroll bar. 


[pnMinPos 
Points to the integer variable that receives the minimum position. 


[pnMaxPos 
Points to the integer variable that receives the maximum position. 


Return Value This function does not return a value. 


Comments If the given window does not have standard scroll bars or is not a scroll bar con- 
trol, the GetScrollRange function copies zero to the IpnMinPos and lpnMaxPos 
‘parameters. 


The default range for a senda scroll bari is 0 through 100. The default range for : 
a scroll bar control is empty (both values are Zero). | 


See Also GetScrollPos, SetScrollPos, SetScrollRange | 


GetSelectorBase ne oon Bal 


DWORD GetSelectorBase(uSelector) 
— UINT uSelector; 


The GetSelectorBase function retrieves the base address of a selector. 


Parameters , uSelector : 
3 Specifies the seledtor whose base address is retrieved. 
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Return Value This function returns the base address of the specified selector. 


— See Also  GetSelectorLimit, SetSelectorBase, SetSelectorLimit 


GetSelectorLimit 


DWORD GetSelectorLimit(uSelector) 
UINT uSelector; 


_ The GetSelectorLimit function retrieves the limit of a selector. 


Parameters uSelector 


Specifies the selector whose limit is being retrieved. 
- Return Value This function returns the limit of the specified selector. 


See Also GetSelectorBase, SetSelectorBase, SetSelectorLimit 


GetStockObject 


HGDIOBJ GetStockObject((nObject) 
int (fnObject; /* type of stock object 


[ 2x | 


The GetStockObject function retrieves a handle of one of the predefined stock 


pens, brushes, or fonts. 


Parameters jnObject 


Specifies the type of stock object for which to retrieve a handle. This parameter 
can be one of the following values: 


Value 


BLACK_BRUSH 
DKGRAY_BRUSH 
GRAY_BRUSH _ 
HOLLOW_BRUSH 
LTGRAY_BRUSH 
NULL_BRUSH 


Meaning 


Black brush. 


Dark-gray brush. 


Gray brush. 
Hollow brush. 


Light-gray brush. 


Null brush. 


Return Value 


Comments 


Example 


See Also 
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Value | Meaning 

WHITE_BRUSH White brush. 

BLACK_PEN Black pen. 

NULL_PEN Null pen. 

WHITE_PEN White pen. — 

ANSI_FIXED_FONT Windows fixed-pitch system font. 
ANSI_VAR_FONT Windows variable-pitch system font. 
DEVICE_DEFAULT_FONT Device-dependent font. | 
OEM_FIXED_FONT OEM-dependent fixed font. 

SYSTEM_FONT 7 System font. By default, Windows uses the SYS- 


tem font to draw menus, dialog box controls, and 
other text. In Windows versions 3.0 and later, the 
system font is a variable-pitch font width; earlier 
versions of Windows use a fixed-pitch system 
| font. | 
SYSTEM_FIXED_FONT Fixed-pitch system font used in Windows ver- 
: sions earlier than 3.0. This object is available for - 
compatibility with earlier versions of Windows. 
DEFAULT_PALETTE | Default color palette. This palette consists of the 
| static colors in the system palette. 


The return value is ‘the handle of the specified obieet if the function is successful. . 
Otherwise, it is NULL. | | 


The DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH objects 
should be used only in windows with the CS_HREDRAW and CS_VREDRAW 
class styles. Using a gray stock brush in any other style of window can lead to mis- 
alignment of brush patterns after a window is moved or sized. The origins of stock 
brushes cannot be adjusted. 


The following example retrieves the handle of a black brush by calling the Get- 


StockObject function, selects the brush into the device context, and fills a 
rectangle by using the black brush: 


HBRUSH hbr, hbrOld; 
hbr = GetStockObject(BLACK_BRUSH) ; 


hbrOld = SelectObject(hdc, hbr); 
Rectangle(hdc, 10, 10, 100, 100); 


GetObject, SetBrushOrg 
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~GetStretchBitMode — | | 2.x | 


int GetStretchBltMode(hdc) 
HDC hdc; /* handle of device context */ 


The GetStretchBltMode function retrieves the current bitmap-stretching mode. 
The bitmap-stretching mode defines how information is removed from bitmaps 
that were compressed by using the StretchBlt function. 


Parameters hdc 
Identifies the device context. 


Return Value The return value specifies the current bitmap-stretching mode— 
STRETCH_ANDSCANS, STRETCH_DELETESCANS, or 
STRETCH_ORSCANS—if the function is successful. 


Comments The STRETCH_ANDSCANS and STRETCH_ORSCANS modes are 
typically used to preserve foreground pixels in monochrome bitmaps. The 
STRETCH_DELETESCANS mode is typically used to preserve color in color bit- 
maps. For more information, see the SetStretchBltMode function. | 


Example The following example uses the GetStretchBltMode function to determine 
whether the current bitmap-stretching mode is STRETCH_DELETESCANS; if 
so, it uses the StretchBlit function to display a compressed bitmap. 


HDC hdcMem; 

int nStretchMode; 

nStretchMode = GetStretchBltMode(hdc); 

if (nStretchMode == STRETCH _DELETESCANS) { 


StretchBlt(hdc, 5@, 175, 32, 32, hdcMem, @, 0, 64, 64, 
SRCCOPY); 


} 


See Also | SetStretchBltMode, StretchBlt 
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GetSubMenu [2x | 


HMENU GetSubMenu(hmenu, nPos) 
HMENU hmenu; /* handle of menu with pop-up menu */ 
int nPos; /* position of pop-up menu +} 


The GetSubMenu function retrieves the handle of a pop-up menu. 


Parameters hmenu 
Identifies the menu with the pop-up menu whose handle is to be retrieved. 


nPos 
| Specifies the position in the given menu of the pop-up menu. Position values 
start at zero (zero-based) for the first menu item. The pop-up menu’s identifier 
cannot be used in this function. 


Return Value The return value is the handle of the given pop-up menu if the function is success- 
ful. Otherwise, it is NULL, indicating that no pop-up menu exists at the given posi- 
tion. 

See Also CreatePopupMenu, GetMenu 


GetSysColor | 


COLORREF GetSysColor(nDspElement) 
int nDspElement; /* display element */ 


The GetSysColor function retrieves the current color of the specified display ele- 
ment. Display elements are the various parts of a window and the Windows dis- 
play that appear on the system screen. 


- Parameters nDspElement 


Specifies the display element whose color is to be retrieved. This parameter can 
be one of the following values: | 


Value Meaning 

COLOR_ACTIVEBORDER Active window border. 
COLOR_ACTIVECAPTION Active window title. 
COLOR_APPWORKSPACE Background color of multiple document 


interface (MDI) applications. 
COLOR_BACKGROUND Desktop. 
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Return Value 
Comments 


See Also 


Value 


COLOR_BTNFACE 
COLOR_BTNHIGHLIGHT 
COLOR_BTNSHADOW | 
COLOR_BTNTEXT 
COLOR_CAPTIONTEXT 


COLOR_GRAYTEXT 


COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_INACTIVECAPTIONTEXT 
-COLOR_MENU | 
COLOR_MENUTEXT 
COLOR_SCROLLBAR 
COLOR_WINDOW 
COLOR_WINDOWFRAME 
COLOR. WINDOWTEXT 


Meaning 


Face shading on push buttons. 
Selected button in a control. 
Edge shading on push buttons. 
Text on push buttons. 


Text in title bar, size button, scroll-bar 
arrow button. 


Grayed (dimmed) text. This color is zero 
if the current display driver does not sup- 
port a solid gray color. 


Background of selected item in a control. 
Text of selected item in a control. 
Inactive window border. 

Inactive window title. 


Color of text in an inactive title. 


Menu background. 
Text in menus. 
Scroll-bar gray area. 
Window background. 
Window frame. 

Text in windows. 


The return value is a red, green, blue (RGB) color value for the specified display — 


element, if the function is successful. 


An application can use the GetR Value, GetG Value, and GetBValue macros to 
extract the various colors from the return value. 


: GetSystemMetrics, SetSysColors 
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GetSysModalWindow eri 


HWND GetSysModalWindow(void) 


The GetSysModal Window function retrieves the handle of the system-modal win- 
dow, if one is present. 


Parameters This function has no parameters. 


Return Value The return value is the handle of the system-modal window, if one is present. 
Otherwise, itis NULL. — 


See Also | SetSysModalWindow 


GetSystemDebugState EXE 
LONG GetSystemDebugState(void) 
The GetSystemDebugState function retrieves information about the state of the 


system. A Windows-based debugger can use this information to determine 
whether to enter hard mode or soft mode upon encountering a breakpoint. 


Parameters This function has no parameters. 

Return Value The return value can be one or more of the following values: 
Value Meaning 
SDS_MENU | Menu is displayed. 
SDS_SYSMODAL System-modal dialog box is displayed. 


SDS_NOTASK QUEUE Application queue does not exist yet and, therefore, the ap- 
| - plication cannot accept posted messages. 


SDS_DIALOG Dialog box is displayed. 


SDS_TASKLOCKED Current task is locked and, therefore, no other task is per- 
mitted to run. 
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GetSystemDir Ban dee 
#include <ver.h> 


UINT GetSystemDir(/pszWinDir, IpszBuf, cbBuf) | 
LPCSTR [pszWinDir; /* address of Windows directory */ 


LPSTR I[pszBuf; /* address of buffer for path */ 
int cbBuf; /* size of buffer +] 


The GetSystemDir function retrieves the path of the Windows system directory. 
This directory contains such files as Windows libraries, drivers, and fonts. 


GetSystemDir is used by MS-DOS applications that set up Windows applica- 
tions; it exists only in the static-link version of the File Installation library. Win- 
dows applications should use the GetSystemDirectory function to determine the 
Windows directory. 


Parameters | [pszWinDir 
| Points to the Windows directory retrieved by a previous call to the Get- 
WindowsDir function. 


lpscBuf , 
Points to the buffer that is to receive the null- terminated string containing the 
path. | 


cbBuf 
Specifies the size, in bytes, of the buffer pointed to by the /pszBuf parameter. 


Return Value The return value is the length of the string copied to the buffer, in bytes, including 
the terminating null character, if the function is sucessful. If the return value is 
greater than the cbBuf parameter, the return value is the size of the buffer required 
to hold the path. The return value is zero if the function fails. | 


Comments An seaicaton must call the GetWindowsDir function before calling the Get- 
SystemDir function to obtain the correct [pszWinDir value. 


The path that this function retrieves does not end with a backslash unless the Win- 
dows system directory is the root directory. For example, if the system directory is 
named WINDOWS\SYSTEM on drive C, the path of the system directory re- 
trieved by this function is C:\WINDOWS\S YSTEM. 


See Also _ _GetSystemDirectory, GetWindowsDir 
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GetSystemDirectory | 


UINT GetSystemDirectory(/pszSysPath, cbSysPath) 
LPSTR IpszSysPath; /* address of buffer for system directory */ 
UINT cbSysPath; _/* size of directory buffer sa 


The GetSystemDirectory function retrieves the path of the Windows system 
directory. The system directory contains such files as Windows libraries, drivers, 
and font files. | 


Parameters IpszSysPath 
Points to the buffer that is to receive the null-terminated oe containing the 
path of the system directory. | 3 


cbSysPath 
Specifies the maximum size, in bytes, of the buffer. This value should be set to 
at least 144 to allow sufficient room in the buffer for the path. 


Return Value The return value is the length, in bytes, of the string copied to the /pszSysPath pa- — 
rameter, not including the terminating null character. If the return value is greater 
than the size specified in the cbSysPath parameter, the return value is the size of 
the buffer required to hold the path. The return value is zero if the function fails. 

~ Comments Applications should not create files in the system directory. If the user is running a 

shared version of Windows, the application will not have write access to the sys- 

tem directory. Applications should create files only in the directory returned by the 

GetWindowsDirectory function. 


The path that this function retrieves does not end with a backslash unless the sys- 
tem directory is the root directory. For example, if the system directory is named 
WINDOWS\SYSTEM on drive C, the path of the system directory retrieved by 
this function is C\WINDOWS\S YSTEM. 


A similar function, GetSystemDir, is intended for use by MS-DOS applications © 
that set up Windows applications. Windows applications should use GetSystem-_ 
Directory, not GetSystemDir. 


Example | The following example uses the GetSystemDirectory function to determine the 
path of the Windows system directory: 


WORD wReturn; 
char szBuf[144]; 


wReturn = GetSystemDirectory((LPSTR) szBuf, sizeof(szBuf)); 
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if (wReturn == Q) | 
MessageBox(hwnd, "function failed", 
"GetSystemDirectory™, MB ICONEXCLAMATION); 


else if (wReturn > sizeof(szBuf)) 
MessageBox(hwnd, "buffer is too small", 
"GetSystemDirectory™, MB _ICONEXCLAMATION);: 


else , 
MessageBox(hwnd, szBuf, "“GetSystemDirectory", MB_OK); 


See Also GetWindowsDirectory 


GetSystemMenu Sets - [ 2.x | 


HMENU GetSystemMenu(hwnd, fRevert) 
HWND hwnd; /* handle of window to own the System menu —s*/ 
BOOL fRevert; /* reset flag | sa | 


The GetSystemMenu function allows the application to access the System menu 
for copying and modification. 


Parameters hwnd | | 
| Identifies the window that will own a copy of the ce menu. 


fRevert 
Specifies the action to be taken. If this parameter is FALSE, the GetSystem- 


~Menu function returns a handle of a copy of the System menu currently in use. 
This copy is initially identical to the System menu, but can be modified. 


If the parameter is TRUE, GetSystemMenu resets the System menu back to 
the Windows default state. The previous System menu, if any, is destroyed. The 
return value is undefined in this case. 


Return Value The return value is the handle of a copy of the System menu, if the fRevert parame- 
a ter is FALSE. If fRevert is TRUE, the return value is undefined. 


Comments Any window that does not use the GetSystemMenu function to make its own 
copy of the System menu receives the standard System menu. : 


The handle that GetSystemMenu returns can be used with the AppendMenu, 
InsertMenu, or ModifyMenu function to change the System menu. The System 
menu initially contains items identified by various identifier values such as 
SC_CLOSE, SC_MOVE, and SC_SIZE. Menu items on the System menu send 
WM_SYSCOMMAND messages. All predefined System-menu items have 
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identifier numbers greater than OxFO00. If an application adds commands to the 
System menu, it should use identifier numbers less than OxFOOO. 


Windows automatically grays (dims) items on the standard System menu, depend- 
ing on the situation. The application can carry out its own checking or graying by 
responding to the WM_INITMENU message, which is sent before any menu is 
displayed. 


Example The following example appends the About item to the System menu: | 


HMENU hmenu; 


hmenu = GetSystemMenu(hwnd, FALSE); 
AppendMenu(hmenu, MF_SEPARATOR, @, (LPSTR) NULL); 
AppendMenu(hmenu, MF_STRING, IDM_ABOUT, "About..."); 


See Also _ AppendMenu, InsertMenu, ModifyMenu 


GetSystemMetrics | 


int GetSystemMetrics(nIndex) 
int nindex; /* system measurement to retrieve my 


The GetSystemMetrics function retrieves the system metrics. The system metrics 
are the widths and heights of the various elements displayed by Windows. Get- 
System Metrics can also return flags that indicate whether the current version of 
the Windows operating system is a debugging version, whether a mouse is pre- 
sent, or whether the meanings of the left and right mouse buttons have been 
exchanged. | 


Parameters nIndex 
Specifies the system measurement to be retrieved. All measurements are given 
in pixels. The system measurement must be one of the following values: 


Value Meaning 

| SM_CXBORDER Width of window frame that cannot be sized. 
SM_CYBORDER | Height of window frame that cannot be sized. 
SM_CYCAPTION Height of window title. This is the title height 


plus the height of the window frame that can- 
not be sized (SM_CYBORDER). 


SM_CXCURSOR Width of cursor, 
SM_CYCURSOR Height of cursor. 
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Value 
SM_CXDOUBLECLK 


SM_CYDOUBLECLK 


SM_CXDLGFRAME 
SM_CYDLGFRAME 


SM_CXFRAME 
SM_CYFRAME 
SM_CXFULLSCREEN 


SM_CYFULLSCREEN 


SM_CXICON 
SM_CYICON 


SM_CXICONSPACING 


SM_CYICONSPACING 


SM_CYKANJIWINDOW 


SM_CYMENU 


SM_CXMIN 
SM_CYMIN 
SM_CXMINTRACK 
SM_CYMINTRACK — 
SM_CXSCREEN _ 
SM_CYSCREEN 
SM_CXHSCROLL 


SM_CYHSCROLL 


Meaning 


Width of the rectangle around the location of 
the first click in a double-click sequence. The 
second click must occur within this rectangle 
for the system to consider the two clicks a 
double-click. 


Height of the rectangle around the location of 
the first click in a double-click sequence. The 
second click must occur within this rectangle 
for the system to consider the two clicks a 
double-click. 7 


Width of frame when window has the 
WS_DLGFRAME style. 


Height of frame when window has the 
WS_DLGFRAME style. 


Width of window frame that can be sized. 
Height of window frame that can be sized. | 


Width of window client area for a full-screen 
window. 


Height of window client area for a full-screen 
window (equivalent to the height of the 
screen minus the height of the window title). 


Width of icon. 
Height of icon. 


Width of rectangles the system uses to posi- 
tion tiled icons. 


Height of rectangles the system uses to posi- 
tion tiled icons. 


Height of Kanji window. 


Height of single-line menu bar. This is 
the menu height minus the height of the 
window frame that cannot be sized 
(SM_CYBORDER). | 


Minimum width of window. | 

Minimum height of window. 

Minimum tracking width of window. 
Minimum tracking height of window. 

Width of screen. 

Height of screen. | 

Width of arrow bitmap on a horizontal scroll 
bar. 

Height of arrow bitmap on a horizontal 
scroll bar. | 


Value 


SM_CXVSCROLL 
SM_CYVSCROLL 


SM_CXSIZE 
SM_CYSIZE 
SM_CXHTHUMB 


SM_CYVTHUMB 
SM_DBCSENABLED 


SM_DEBUG 


SM_MENUDROPALIGNMENT 


SM_MOUSEPRESENT 


SM_PENWINDOWS 


~ SM_SWAPBUTTON 
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Meaning 
Width of arrow bitmap on a vertical scroll bar. 


Height of arrow bitmap on a vertical scroll 
bar. 


Width of bitmaps contained in the title bar. 
Height of bitmaps contained in the title bar. 


‘ Width of scroll box (thumb) on horizontal 


scroll bar. 
Height of scroll box on vertical ll bar. 


Nonzero if current version of Windows uses 
double-byte characters; otherwise, this value 
returns zero. 


Nonzero if the Windows version is a debug- 
ging version. | | 
Alignment of pop-up menus. If this value is 
zero, the left side of a pop-up menu 1s aligned 
with the left side of the corresponding menu- 
bar item. If this value is nonzero, the left side 
of a pop-up menu is aligned with the right 
side of the corresponding menu-bar item. — 
Nonzero if the mouse hardware is installed. 


Handle of the Pen Windows dynamic-link — 
library (DLL) if Pen Windows is installed. 
Nonzero if the left and right mouse buttons | 
are swapped. 


Return Value The return value specifies the requested system metric if the function is successful. 


Comments System metrics depend on the type of screen and may vary from screen to screen. 
See Also GetSysColor, SystemParametersInfo 


GetSystemPaletteEntries 


UINT GetSystemPaletteEntries( hdc iStart, cEntries, ne | aoe | 
HDC hdc; — /* handle of device context _ | */ 


UINT iStart; /* first palette entry to retrieve ed, i ee 
UINT cEntries; /* number of entries to retrieve __ al | 


PALETTEENTRY FAR* PRE /* address of structure for palette entries | +] 
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Parameters 


Return Value 


Example 


See Also 


The GetSystemPaletteEntries function retrieves a range of palette entries from 
the system palette. 


hdc | 
_ Identifies the device context. 


iStart 
Specifies the first system-palette entry to be retrieved. 


cEntries | 
Specifies the number of system-palette entries to be retrieved. 


lppe 
Points to an array of PALETTEENTRY structures that receives the paletic en- 
tries. The array must contain at least as many structures as specified by the 
cEntries parameter. The PALETTEENTRY structure has the following form: 


typedef struct tagPALETTEENTRY { /* pe */ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is the number of entries retrieved from the system palette, if the 
function is successful. Otherwise, it is zero. 


The following example uses the GetDeviceCaps function to determine whether 
the specified device is palette-based. If the device supports palettes, the Get- 
SystemPaletteEntries function is called, using GetDeviceCaps again, this time to 


- determine the number of entries in the system palette. 


PALETTEENTRY peLMAXNUMBER] ; 


hdc = GetDC(hwnd); 


if (!(GetDeviceCaps(hdc; RASTERCAPS) & RC_PALETTE)) { 


ReleaseDC(hwnd, hdc); 


break; 

} 

GetSystemPaletteEntries(hdc, @, GetDeviceCaps(hdc, SIZEPALETTE), 
pe); 


ReleaseDC(hwnd, hdc); 


GetDeviceCaps, GetPaletteEntries 
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GetSystemPaletteUse _ faa] 


UINT GetSystemPaletteUse(hdc) 
HDC hdc; /* handle of device context */ 


The GetSystemPaletteUse function determines whether an application has access 
to the entire system palette. 2 


Parameters Ade 
| Identifies the device context. This device context must support color palettes. 


Return Value The return value specifies the current use of the system palette, if the function is 
successful. This parameter can be one of the following values: 


Value Meaning 

SYSPAL_NOSTATIC System palette contains no static colors except black and 
white. : 

SYSPAL_STATIC System palette contains static colors that do not change 


when an application realizes its logical palette. 


| Comments — The system palette contains 20 default static colors that are not changed when an os 
application realizes its logical palette. An application can gain access to most of 
these colors by calling the SetSystemPaletteUse function. , 


Example The following example uses the GetDeviceCaps function to determine whether 
ee the specified device is palette- based. If the device supports oe the Get- 
SystemPaletteUse function is called. 


WORD nUse; 


hdc = GetDC(hwnd); 

if ((GetDeviceCaps(hdc, RASTERCAPS) & RC_ PALETTE). = = 0) { 
ReleaseDC(hwnd, hdc); 
break; 

} 

nUse = GetSystemPaletteUse(hdc) ; 

ReleaseDC(hwnd, hdc); 


See Also GetDeviceCaps, SetSystemPaletteUse : 
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GetTabbedTextExtent F Gta. 


DWORD GetTabbedTextExtent(hdc, lpszString, cChars, cTabs, IpnTabs) 
sa | 


HDC hdc; /* handle of device context 

LPCSTR IpszString; /* address of string 3 */ 
int cChars; /* number of characters in string +} 
int cZabs; /* number of tab positions */ 
int FAR* [pnTabs; /* address of array of tab positions al 


The GetTabbedTextExtent function computes the width and height of a charac- 
ter string. If the string contains one or more tab characters, the width of the string 
is based upon the specified tab stops. GetTabbedTextExtent uses the currently 
selected font to compute the dimensions of the string. 


Parameters hdc 
_ Identifies the device context. 
[pszString | 
Points to a character string. 


cChars 
Specifies the number of characters in the text string. 


cTabs ? 
Specifies the number of tab-stop positions in the array pointed to by the 
[pnTabs parameter. 


lpnTabs 
Points to an array containing the tab-stop positions, in device units. The tab 
stops must be sorted in increasing order; the smallest x-value should be the first 
item in the array. 


Return Value The low-order word of the return value contains the string width, in logical units, 
if the function is successful; the high-order word contains the string Be 


Comments The current clipping region does not affect the width and height returned Oy the 
GetTabbedTextExtent function. 


Since some devices do not place characters in regular cell arrays (that is they kern 
the characters), the sum of the extents of the characters in a string may not be 
equal to the extent of the string. 


Example 


See Also 
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_ If the cTabs parameter is zero and the [pnTabs parameter is NULL, tabs are ex- 


panded to eight times the average character width. If cTabs is 1, the tab stops are _ 
separated by the distance specified by the first value in the ay to which [pnTabs 
points. 


The following example uses the LOWORD and HIWORD macros to retrieve the 
width and height of the string from the value returned by the GetTabbedTextEx- 
tent function: 


LPSTR IpszTabbedText = "Column 1\tColumn 2\tTest of TabbedTextOut"; 
int aTabs[2] = { 150, 300 }; 

DWORD dwTabExtent; 

WORD wStringWidth, wStringHeight; 


dwlabExtent = GetTabbedTextExtent(hdc, /* handle of device context */ 


lpszTabbedText, /* address of text | * / 
Istrlen(|lpszTabbedText), /* number of characters * / 
sizeof(aTabs) / sizeof(int), | /* number of tabs in array ¥*/ 
alabs); /* array for tab positions */ | 


wStringWidth = LOWORD(dwTlabExtent); /* gets width of string */ 
wStringHeight = HIWORD(dwTabExtent); /* gets height of string  ¥*/ 


GetTextExtent, TabbedTextOut 


GetlempDrive ee eee i 


BYTE GetTempDrive(chDriveLetter) 


char chDriveLetter; 


Parameters 


~~ Return Value 


/* ignored | 


The GetTempDrive function returns a letter that specifies a disk drive the applica- 
tion can use for temporary files. : 


chDriveLetter : 
This parameter is ignored. 


The return value specifies a disk drive for temporary files if the function is success- _ 
ful. If at least one hard disk drive is available, the function returns the letter of the 

first hard disk drive (usually C). If no hard disk drives are available, the function | 
returns the letter of the current drive. | | 
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Example The following example uses the GetTempDrive function to determine a suitable 
_ disk drive for temporary files: | 


char szMsg[80]; 
BYTE bTempDrive; 


bTempDrive = GetTempDrive(Q); 
sprintf(szMsg, "temporary drive: %c", blempDrive); 


MessageBox(hwnd, szMsg, “GetTempDrive", MB_OK); 


See Also | GetTempFileName 


GetTempFileName — [2x | 


int GetTempFileName(bDriveLetter, [pszPrefixString, uUnique, IpszTempFileName) 


BYTE bDriveLetter; /* suggested drive ad 
LPCSTR IpszPrefixString; /* address of filename prefix **/ 
UINT uUnique; /* number to use as prefix 7] 
LPSTR I[pszTempFileName; /* address of buffer for created filename i 


The GetTempFileName function creates a temporary filename of the following 
form: 


drive:\path\prefixuuuu. TMP 


The following list describes the filename syntax: 


Element Description 
drive Drive letter specified by the bDriveLetter parameter 
path Path of the temporary file (either the Windows directory or the directory 

specified in the TEMP environment variable) 

prefix All the letters (up to the first three) of the string pointed to by the 
lpszPrefixString parameter 

uuuu _ Hexadecimal value of the number specified by the uUnique parameter 

Parameters bDriveLetter 


Specifies the suggested drive for the temporary filename. If this parameter is 
zero, Windows uses the current default drive. 


lpszPrefixString 
Points to a null-terminated string to be used as the temporary filename prefix. 
This string must consist of characters in the OEM-defined character set. 


Return Value 


Comments 


Example 
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uUnique 
Specifies an unsigned short integer. If this parameter is nonzero, it will be ap- 
pended to the temporary filename. If the parameter is zero, Windows uses the 
current system time to create a number to append to the filename. 


— lpszTempFileName 


Points to the buffer that will receive the temporary filename. This string con- 
sists of characters in the OEM-defined character set. This buffer should be at 
least 144 bytes in length to allow sufficient room for the path. | 


The return value specifies a unique numeric value used in the temporary filename. 


If the uUnique parameter is nonzero, the return value specifies this same number. 


Temporary files created with this function are not automatically deleted when Win- 
dows shuts down. 


To avoid problems resulting from converting an OEM character string to a Win- 
dows string, an application should call the _lopen function to create the temporary 
file. | 


_ The GetTempFileName function uses the suggested drive letter for creating the 


temporary filename, except in the following cases: 


= Ifahard disk is present, GetTempFileName always uses the drive letter of the 
first hard disk. | 


= If, however, a TEMP environment variable i is defined and its value begins with 
a drive letter, that drive letter is used. | 


If the TF_FORCEDRIVE bit of the bDriveLetter parameter is set, the prededing | 
exceptions do not apply. The temporary filename will always be created in the cur- 
rent directory of the drive specified by bDriveLetter, regardless of the Digsence of 


ahard disk or the TEMP environment variable. 


If the ae parameter is zero, GetTempFileName attempts to form a unique 
number based on the current system time. If a file with the resulting filename ex- 
ists, the number is increased by one and the test for existence is repeated. This con- 


_ tinues until a unique filename is found; GetTempFileName then creates a file by 


that name and closes it. No attempt is made to create and open the file when 


uUnique 1s nonzero. 


: . The following example uses the GetTempFileName function to create a unique 
temporary filename on the first available hard ve 


HFILE hfTempFile; 


~ char szBuf[144]; 
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/* Create a temporary file. */ 
GetTempFileName(@, "“tst", 0, szBuf); 
hfTempFile = _lcreat(szBuf, Q@); 

if (hfTempFile == HFILE_ERROR) { 


- ErrorHandler(); 
} : 


See Also GetTempDrive, _lopen 


GetTextAlign [2x] 


UINT GetTextAlign(hdc) 
HDC hdc; /* handle of device context */ 


The GetTextAlign function retrieves the status of the text-alignment flags for the 
given device context. | 


Parameters hdc 
Identifies the device context. 


Return Value The return value specifies the status of the text-alignment flags. This parameter 

can be one or more of the following values: 

Value Meaning | 

TA_BASELINE - Specifies alignment of the x-axis and the base line of the 
chosen font within the bounding rectangle. 

TA_BOTTOM — Specifies alignment of the x-axis and the bottom of the bound- 

| ing rectangle. 

TA_CENTER Specifies alignment of the y-axis and the center of the bound- 
ing rectangle. 

TA_LEFT Specifies alignment of the y-axis and the left side of the 
bounding rectangle. 

TA_NOUPDATECP Specifies that the current position is not updated. 

TA_RIGHT _ Specifies alignment of the y-axis and the right side of the 
bounding rectangle. 

TA_TOP _ Specifies alignment of the x-axis and the top of the bounding 
rectangle. 


TA_UPDATECP Specifies that the current position is updated. 


Comments 


Example 


See Also 
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The text-alignment flags retrieved by the GetTextAlign function are used by the 
TextOut and ExtTextOut functions. These flags determine how TextOut and 
ExtTextOut align a string of text in relation to the string’s larang point. 


The text-alignment flags are not necessarily single-bit flags and may be equal to 
zero. To test whether a flag 1 is set, an application should follow three steps: 


1. Apply the bitwise OR operator to the flag and its related flags. 
Following are the groups of related flags: 
= TA_LEFT, TA_CENTER, and TA_RIGHT 
" TA_BASELINE, TA_BOTTOM, and TA_TOP 
*" TA_NOUPDATECP and TA_UPDATECP 


2. Apply the bitwise AND operator to the result and the return value of the 
GetTextAlign function. 


3. Test for the equality of this result and the flag. 


The following example uses the method described in the preceding Comments sec- 
tion to determine whether text is aligned at the right, left, or center of the bounding 
rectangle. If the TA_RIGHT flag is set, the SetTextAlign function is used to set _ 


the text alignment to the left side of the rectangle. 


switch ((TA_LEFT | TA_CENTER | TA_RIGHT) & GetTextAlign(hdc)) { 
case TA_RIGHT: . 
TextOut(hdc, 200, 100, "This is TA_RIGHT.", 17); 
SetTextAlign(hdc, TA_LEFT); 
TextOut(hdc, 200, 120, “This is TA_LEFT.", 16); 
break; . | 
case TA_LEFT: 


case TA_CENTER: 


} 


ExtTextOut, SetTextAlign, TextOut 
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GetTextCharacterExtra “ a [ex] 


int GetTextCharacterExtra(hdc) 
HDC hdc; /* handle of device context a | 


The GetTextCharacterExtra function retrieves the current setting for the amount 
of intercharacter spacing. Graphics device interface (GDI) adds this spacing to 
each character, including break characters, when it writes a line of text to the 
device context. 


Parameters hdc 
Identifies the device context. 


Return Value The return value specifies the amount of intercharacter spacing if the function is 
successful. | 

Comments The default value for the amount of intercharacter spacing is zero. 

See Also — SetTextCharacterExtra 


GetTextColor - Bin 2x | 


COLORREF GetTextColor(hdc) 
HDC hdc; /* handle of device context */ 


The GetTextColor function retrieves the current text color. The text color is the 
foreground color of characters drawn by using the graphics device interface (GDI) 
text-output functions. 


Parameters hdc 
Identifies the device context. 


Return Value The return value specifies the current text color as a red, green, blue (RGB) color 
value, if the function is successful. 


Example The following example sets the text color to red if the GetTextColor function de- 
termines that the current text color is black: 
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DWORD dwColor; 


dwColor = GetTextColor(hdc); 
if (dwColor == RGB(@, @, @)) /* if current color is black */ 
SetTextColor(hdc, RGB(255, @, @)); /* sets color to red */ 


See Also GetBkColor, GetBkMode, SetBkMode, SetTextColor 


GetTextExtent eee =i 


DWORD GetTextExtent(hdc, [pszString, cbString) 


HDC hdc; /* handle of device context = */ 
LPCSTR IpszString; /* address of string ‘| 
int cbString; /* number of bytes in string */ 


The GetTextExtent function computes the width and height of a a of text, 
using the current font to compute the dimensions. 


Parameters hdc 
Identifies the device context. 


[pszString 
Points to a character string. 


cbString 
Specifies the number of bytes in the string. 


Return Value The low-order word of the return value contains the string width, in logical units, 
if the function is successful; the high-order word contains the string height. 


Comments The current clipping region does not affect the width and height returned by the 
_ GetTextExtent function. 


Since some devices do not place characters in regular cell arrays (that is, they kern 
characters), the sum of the extents of the characters in a string may not be equal to 
the extent of the string. 


Example The following example retrieves the number of Sseseteiel ina string by using the 
7 Istrlen function, calls the GetTextExtent function to retrieve the dimensions of 
the string, and then uses the LOWORD macro to determine the string width, in 
logical units: 
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— dwExtent 


See Also 


—GetTextExtentPoint 


DWORD dwExtent; 
WORD wlextWidth; 
LPSTR IpszJustified = "Text to be justified in this test."; 


GetTextExtent(hdc, IpszdJustified, Istrlen(lpszJustified)); 


wlextWidth LOWORD( dwExtent); 


GetTabbedTextExtent, SetTextJustification 


BOOL GetTextExtentPoint(hdc, [pszString, cbString, IpS a 


HDC hdc; 
LPCSTR [pszString; 
int cbString; 

SIZE FAR® IpSize; 


Parameters 


/* handle of device context a 
/* address of text string */ 
/* number of bytes in string if 

_ /* address if structure for string size i 


The GetTextExtentPoint function computes the width and height of the specified 
text string. The GetTextExtentPoint function uses the currently selected font to 
compute the dimensions of the string. The width and height, in logical units, are 
computed without considering any clipping. 


The GetTextExtentPoint function may be used as either a wide-character func- 
tion (where text arguments must use Unicode) or an ANSI function (where text 
arguments must use characters from the Windows 3.x character set). 


hdc ae 
Identifies the device context. 


IpszString 
Points to a text string. | 


cbString | 


Specifies the number of bytes in the text string. 


| IpSi ize 


Points to a SIZE structure that ‘all receive the ‘iniensions of the string The 
SIZE structure has the following form: 


typedef struct tagSIZE { 
int cx; 
int cy;. 

} SIZE; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
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Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments Because some devices do not place characters in regular cell arrays—that is, be- 


cause they carry out kerning—the sum of the extents of the characters in a string 
may not be equal to the extent of the string. 


The calculated width takes into account the intercharacter spacing set by the 
SetTextCharacterExtra function. 


See Also _ SetTextCharacterExtra 


GetTextFace 4 ea! 


int GetTextFace(hdc, cbBuffer, lpszFace) 


HDC hdc; /* handle of device context a | 
int cbBuffer; /* size of buffer for-face name > */ 
LPSTR [pszFace; /* pointer to buffer for face name */ 


The GetTextFace function copies the typeface name of the current font into a 
buffer. The typeface name is copied as a null-terminated string. 


Parameters hdc | | 
Identifies the device context. 


cbBuffer | | 
Specifies the buffer size, in bytes. If the typeface name is longer than the num- 
ber of bytes specified by this parameter, the name is truncated. | 


[pszFace | 
Points to the buffer for the typeface name. 


Return Value The return value specifies the number of bytes copied to the buffer, not including 
the terminating null character, if the function is successful. Otherwise, it is zero. 


Example The following example uses the GetTextFace function to retrieve the name of the 
current typeface, calls the SetTextAlign function so that the current position is up- 
dated when the TextOut function is called, and then writes some introductory text 
and the name of the typeface by calling TextOut: 


int nFaceNameLen; | 
char aFaceName[8Q]; 
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nFaceNameLen = GetTextFace(hdc, /* returns length of string */ 


sizeof (aFaceName), /* size of face-name buffer 2 / 

(LPSTR) aFaceName) ; /* address of face-name buffer */ 
SetTextAlign(hdc, : 

TA_UPDATECP) ; /* updates current position * / 
Movelo(hdc, 100, 100); /* sets current position x / 
TextOut(hdc, 0, @, /* uses current position for text */ 


"This is the current face name: ", 31); 
TextOut(hdc, @, @, aFaceName, nFaceNameLen) ; 


See Also — GetTextMetrics, SetTextAlign, TextOut 


GetTextMetrics [2x | 


BOOL GetTextMetrics(hdc, lptm) 
HDC hdc; /* handle of device context */ 
TEXTMETRIC FAR* Ipim; /* pointer to structure for font metrics | 


The GetTextMetrics function retrieves the metrics for the current font. 


Parameters hdc 
Identifies the device context. 


lptm 
Points to the TEXTMETRIC structure that receives the metrics. The TEXT- 
METRIC structure has the following form: 


typedef struct tagTEXTMETRIC { /* tm */ 

int tmHeight; 
int tmAscent; 
int tmDescent; 
int tmInternalLeading; 
int. tmExternalLeading; 
int tmAveCharWidth; 
int tmMaxCharWidth; 
‘int tmWeight; 
BYTE tmItalic; 

— BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; 
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int tmOverhang; 

int tmDigitizedAspectX; 

int tmDigitizedAspectyY; 
} TEXTMETRIC; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value. The return value is nonzero if the function is successful. Otherwise, it is zero. 


Example The following example calls the GetTextMetrics function and then uses informa- 
tion in a TEXTMETRIC structure to determine how many break characters are in 
a string of text: 


TEXTMETRIC tm; 

int j, cBreakChars, cchString; 

LPSTR IpszJustified = "Text to be justified in this test."; 
GetTextMetrics(hdc, &tm); 

cchString = Istrien(|lpszJustified) ; 

for (cBreakChars = 0, j = 0; j < cchString; j++) 


if(*(IlpszJustified + j) == (char) tm.tmBreakChar) 
cBreakChars++; 


See Also GetTextAlign, GetTextExtent, GetTextFace, SetTextJ ustification 


GetThresholdEvent oe [2x] 


int FAR* GetThresholdEvent(void) 


This function is obsolete. Use the Windows multimedia audio functions instead. 
For information about these functions, see the Microsoft Windows Multimedia Pro- 
grammer’s Reference. 
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GetThresholdStatus oe, rex] 
int GetThresholdStatus(void) 


This function is obsolete. Use the Windows multimedia audio functions instead. 
For information about these functions, see the Microsoft Windows Multimedia Pro- 
grammer’s Reference. 


GetTickCount [2x] 
DWORD eerie tonne yon)... | 
The GetTickCount function retrieves the number of milliseconds that have 
elapsed since Windows was started. 7 


Parameters This function has no pacers: 


- Return Value The return value specifies the number of milliseconds that have elapsed since Win- 
dows was started. 


Comments The internal timer will wrap around to zero if Windows is run continuously for ap- 
proximately 49 days. 


The GetTickCount function is identical to the GetCurrentTime function. Appli- 
cations should use GetTickCount, because its name matches more ese with 
what the function does. 


Example The following example calls GetTickCount to determine the number of millisec- 
onds that Windows has been running, converts the value into seconds, and dis- 
plays the value in a message box: 


char szBuf[255]; 


sprintf(szBuf, "Windows has been running for %lu seconds\n", 
GetTickCount() / 100@L); 
MessageBox(hwnd, szBuf, "", MB_OK); 
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GetTimerResolution as _ ae [ 3.1 | 


DWORD GetTimerResolution(void) 


The GetTimerResolution function retrieves the number of microseconds per 


timer tick. 
Parameters __ This function has no parameters. 
Return Value The return value is the number of microseconds per timer tick. 
See Also | GetTickCount, SetTimer 


GetlopWindow ~~ Pax] 


HWND GetTopWindow(hwnd) 
HWND hwnd; /*handle of parent window = */ 


The GetTopWindow function retrieves the handle of the top-level child window 
that belongs to the given parent window. If the parent window has no child win- _ 
dows, this function returns NULL. | 7 3 


Parameters © hwnd 
Identifies the parent window. If this parameter is NULL, the function returns 
the first child window of the desktop window. 


Return Value The return value is the handle of the top-level child window in a parent window’s 
linked list of child windows. The return value is NULL if no child windows exist. 


See Also EnumWindows, GetParent, IsChild 


GetUpdateRect ped Oe os, al 


BOOL GetUpdateRect(hawnd, ibe fErase) — ee 
HWNDhwnd _—s/* handle of window ee if eee 

~ RECT FAR* Ipre; _/* address of structure for update rectangle Pr eo 
BOOL fErase; _ F* erase flag 7 | **/ 
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Parameters 


Return Value 


Comments 


See Also 


The GetUpdateRect function retrieves the coordinates of the smallest rectangle 
that completely encloses the update region of the given window. If the window 
was created with the CS_OWNDC style and the mapping mode is not 
MM_TEXT, GetUpdateRect gives the rectangle in logical coordinates; other- 
wise, GetUpdateRect gives the rectangle in client coordinates. If there is no up- 
date region, GetUpdateRect makes the rectangle empty (sets all coordinates to 
ZerO). 


| hwnd 


Identifies the window whose update re region is to be retrieved. 


pre 
Points to the RECT structure that receives the client coordinates of the enclos- 
ing rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* ro */ 
| int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


An application can set this parameter to NULL to determine whether an update 
region exists for the window. If this parameter is NULL, the GetUpdateRect 
function returns nonzero if an update region exists, and zero if one does not. 
This provides a simple and efficient means of determining whether a 
WM_PAINT message resulted from an invalid area. 


fErase 


Specifies whether to erase the background in the update region. If this parame- 
ter is TRUE and the update region is not empty, the background is erased. To 
erase the background, the GetUpdateRect function sends a 
WM_ERASEBKGND message to the given window. 


The return value is nonzero if the update region is not empty. Otherwise, it is zero. 


The update rectangle retrieved by the BeginPaint function is identical to that re- 
trieved by the GetUpdateRect function. 


BeginPaint automatically validates the update region, so any call to Get- 


UpdateRect made immediately after the call to BeginPaint retrieves an empty 
update region. 


BeginPaint, GetUpdateRgn, InvalidateRect, UpdateWindow, ValidateRect 
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GetUpdateRgn ee 5 


int GetUpdateRgn(hwnd, hrgn, fErase) 


HWND hwnd; 
HRGN hrgn; 
BOOL fErase; 


Parameters 


Return Value 


Comments | 


See Also. 


GetVersion 


/* handle of window */ 
/* handle of region */ 
/* erase flag a 


The GetUpdateRgn function retrieves the update region of a window. The coordi- 
nates of the update region are relative to the upper-left corner of the window (that — 
is, they are client coordinates). 


hwnd 
Identifies the window whose update feeI0n is to be retrieved. 
hrgn 
Identifies the update region. 
fErase 
Specifies whether the window background should be erased and snether non- 


client areas of child windows should be drawn. If this parameter is FALSE, no 
drawing is done. | 


The return value is SIMPLEREGION (region has no overlapping borders), : 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region | 


1s empty), if the function is successful. Otherwise, the return value is ERROR. 


The BeginPaint function automatically validates the update region, so any call to 
the GetUpdateRgn function made immediately after the call to aera re- 
trieves an empty update region. 


BeginPaint, GetUpdateRect, InvalidateRgn, UpdateWindow, ValidateRgn 


DWORD GetVersion(void) 


Parameters 


Return Value 


ives The GetVersion function retrieves the current version numbers of the Windows 


and MS-DOS operation systems. 


_ This function has no PARINEEEES. 


: The return alae specifies the major and minor version numbers of Windows cea 
of MS-DOS, it the function is successtul. | 
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Comments 


Example 


The low-order word of the return value contains the version of Windows, if the 
function is successful. The high-order byte contains the minor version (revision) 
number as a two-digit decimal number. For example, in Windows 3.1, the minor 
version number is 10. The low-order byte contains the major version number. 


The high-order word contains the version of MS-DOS, if the function is success- 
ful. The high-order byte contains the major version; the low-order byte contains 
the minor version (revision) number. 


The following example uses the GetVersion function to display the Windows and 
MS-DOS version numbers: 


int len; 
char szBuf[8@]; 
DWORD dwVersion; 


dwVersion = GetVersion(); 

len = sprintf(szBuf, "Windows version %4d.%d\n", 
LOBYTE(LOWORD(dwVersion)), 
HIBYTE(CLOWORD(dwVersion))); 

sprintf(szBuf + len, "MS-DOS version %d.%d", 
HIBYTECHIWORD(dwVersion)), 
LOBYTECHIWORD(dwVersion))); 


MessageBox(NULL, szBuf, "GetVersion", MB ICONINFORMATION); 


‘Note that the major and minor version information is reversed between the Win- 


dows version and MS-DOS version. 
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DWORD GetViewportExt(hdc) 


HDC hdc; 


Parameters 


Return Value 


/* handle of device context */ 


The Get ViewportExt function retrieves the x- and y-extents of the device con- 
text’s viewport. 


hdc 
Identifies the device context. 


The low-order word of the return eaiad contains the x- -extent, in device units, if the 
function is successiul, the high-order word contains the y-extent. 


Example 


See Also 
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The following example uses the Get ViewportExt function and the LOWORD | 
and HTWORD macros to retrieve the x- and y-extents for a device context: 


HDC hdc; 
DWORD dw; 
int xViewExt, yViewExt; 


hdc = GetDC(hwnd); 

dw. = GetViewportExt(hdc);: 
ReleaseDC( hwnd, hdc); 
xViewExt = LOWORD(dw); 
yViewExt = HIWORD(dw); 


Set ViewportExt 


GetViewportExtEx o aa 


BOOL GetViewportExtEx(hdc, [pSize) 


HDC hdc; 
SIZE FAR* [pSize; 


Parameters 


Return Value © 


The GetViewportExtEx function retrieves the x- and y- -extents of the device con- 7 
text’s viewport. co | 


hdc 3 
Identifies the device context. 


[pSize 
Points to a SIZE structure. The x- and y-extents (in device aniés) are placed in 
this structure. *s 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


GetViewportOrg aa 


DWORD GetViewportOrg(hdc) 
HDC hdc; —s/* handle of device context sa fe 


The GetViewportOrg function retrieves the x- and y-coordinates of the origin of 
the viewport associated with the given device context. | 
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Parameters | hdc 
Identifies the device context. 


Return Value The low-order word of the return value contains the viewport origin’s x-coordi- _ 
nate, in device coordinates, if the function is successful; the high-order word con- 
tains the y-coordinate of the viewport origin. | 


Example The following example uses the Get ViewportOrg function and the LOWORD 
and HTWORD macros to retrieve the x- and y-coordinates of the viewport origin: 


HDC hdc; 
DWORD dw; 
int xView0Org, Wieworg: 


hdc = GetDC(hwnd); 
dw GetViewportOrg(hdc); 
ReleaseDC( hwnd, hdc); 
xViewOrg = LOWORD(dw); 
yViewOrg = HIWORD(dw); 


See Also GetWindowOrg, Set ViewportOrg 
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BOOL GetViewportOrgEx(hdc, IpPoint) 


HDC hdc; 

POINT FAR* /pPoint; 
The Get ViewportOrgEx function retrieves the x- and y-coordinates of the origin 
of the viewport associated with the specified device context. 

Parameters — hdc 


Identifies the device context. 


lpPoint 
Points to a POINT structure. The origin of the viewport (in device coordinates) 
is placed in this structure. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
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GetWinDebuginfo era 


BOOL GetWinDebugInfo(/pwdi, flags) | | 
WINDEBUGINFO FAR* Ipwdi; /* address of WINDEBUGINFO structure a 
UINT flags; /* flags for returned information st 


The GetWinDebugInfo function retrieves current system-debugging information 
for the debugging version of the Windows 3.1 operating system. 


Parameters. lpwdi 
Points to a WINDEBUGINFO structure that is filled with debugging informa- 
tion. The WINDEBUGINFO structure has the wae form: 


typedef struct tagWINDEBUGINFO { 
UINT flags; 
DWORD = dwOptions; 
DWORD = dwFilter; 
‘char achAllocModule[8]; 
DWORD dwAllocBreak; 
DWORD dwAllocCount; 

} WINDEBUGINFO; ~ 


For a full description of this structure, see the M. aaah Windows Program- 
mer’s Reference, Volume 3. 


flags 
Specifies which members of the WINDEBUGINFO structure should be filled 


in. This parameter can be one or more of the following values: 


Value — Meaning | 
WDI_OPTIONS Fill in the dwOptions member of WINDEBUGINFO. 
WDI_FILTER Fill in the dwFilter member of WINDEBUGINFO. 


WDLALLOCBREAK Fill in the achAllocModule, dwAllocBreak, and 
dwAllocCount members of WINDEBUGINFO. 


Return Value The return value is nonzero if the function is successful. It is zero if the pointer 
specified in the /pwdi parameter is invalid or if the function is not called in the de- 
bugging version of Windows 3.1. 


7 Comments The flags member of the returned WINDEBUGINFO structure is Set to the | 
values supplied in the flags parameter of this function. | PRGA eee | 


SeeAlso §  §—- Set WinDebugInfo 
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GetWindow | ax] 


HWND GetWindow(iwnd, fuRel) | 
HWND hwnd; __s—s/* handle of original window | 
UINT fuRel; /* relationship flag a | 


The Get Window function retrieves the handle of a window that has the specified 
relationship to the given window. The function searches the system’s list of top- 
level windows, their associated child windows, the child windows of any child 
windows, and any siblings of the owner of a window. 


Parameters hwnd 
Identifies the original window. 
fuRel 
Specifies the relationship between the original window and the returned win- 
dow. This parameter can be one of the following values: 
Value Meaning 


GW_CHILD Identifies the window’s first child window. 


GW_HWNDFIRST Returns the first sibling window for a child window; other- 
wise, it returns the first top-level window in the list. 


GW_HWNDLAST Returns the last sibling window for a child window; other- 
wise, it returns the last top-level window in the list. 


GW_HWNDNEXT Returns the sibling window that follows the given window 
in the list. 


GW_HWNDPREV Returns the previous sibling window in the list. 
GW_OWNER Identifies the window’s owner. 


Return Value The return value is the handle of the window if the function is successful. Other- | 
wise, it is NULL, indicating either the end of the system’s list or an invalid fuRel 
parameter. 


See Also EnumWindows, FindWindow 


GetWindowDC tt fax] 
HDC GetWindowDC(hwnd) | 
HWND hwnd; /* handle of window */ 


The GetWindowDC function retrieves a device context for the entire window, 
including title bar, menus, and scroll bars. A window device context permits 


Parameters 


Return Value 


Comments 


See Also 
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painting anywhere in the window, because the origin of the context is the upper- 
left corner of the window instead of the client area. 


GetWindowDC assigns default attributes to the device context each time it re- 
trieves the context. Previous attributes are lost. 


hwnd 
Identifies the window whose device context is to be retrieved. 


The return value is the handle of the device context for the given window, if the 
function is successful. Otherwise, it is NULL, indicating an error or an invalid 
hwnd parameter. 


The GetWindowDC function is intended to be used for special painting effects 
within a window’s nonclient area. Painting in nonclient areas of any window is not 
recommended. 


The GetSystemMetrics function can be used to retrieve the dimensions of various 
parts of the nonclient area, such as the title bar, menu, and scroll bars. 


After painting is complete, the ReleaseDC function must be called to release the ~ 
device context. Failure to release a window device context will have serious ef- 
fects on painting requested by applications. 


BeginPaint, GetDC, GetSystemMetrics, ReleaseDC 
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DWORD GetWindowExt(hdc) 


HDC hdc; 


Parameters 


Return Value 


/* handle of device context **/ 


The GetWindowExt function retrieves the x- and y-extents of the window as- 
sociated with the given device context. 


hdc 
| Identifies the device context. 


The return value specifies the x- and y-extents, in logical units, if the function 1s 
successful. The x-extent is in the low-order word; the y-extent is in the high- -order 
word. 7 | 
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Example _ The following example uses the GetWindowExt function and the LOWORD and 
HIWORD macros to retrieve the x- and y-extents of a window: 


HDC hdc; 
DWORD dw; 
int xWindExt, yWindExt; 


hdc = GetDC(hwnd); 
dw = GetWindowExt(hdc); 
ReleaseDC(hwnd, hdc); 


xWindExt = LOWORD(dw); 
yWindExt = HIWORD(dw); 


See Also | SetWindowExt 


GetWindowExtEx [31 | 


BOOL GetWindowExtEx(hdc, [pSize) 


HDC hdc; | 
SIZE FAR* [pSize; | 
The GetWindowExtEx function retrieves the x- and y-extents of the window 
associated with the specified device context. 
Parameters hdc 
Identifies the device context. 
[pSize 
Points to a SIZE structure. The x- and y-extents (in logical units) are placed in. 
this structure. 


Return Value The return value is nonzero if the function is successful. Otherwise, itis zero. — 


GetWindowLong sy Be 


LONG GetWindowLong(hwnd, nOffset) 
HWND hwnd; /* handle of window 5 ag 
int nOffset; /* offset of value to retrieve © */ 


The GetWindowLong function retrieves a long value at the specified offset into 
the extra window memory of the given window. Extra window memory is re- 
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served by specifying a nonzero value in the cbWndExtra member of the — 
WNDCLASS structure used with the RegisterClass function. 


Parameters hwnd 
Identifies the window. 


nOffset | 
Specifies the zero-based byte offset of the value to be retrieved. Valid values 
are in the range zero through the number of bytes of extra window memory, 
minus four (for example, if 12 or more bytes of extra memory was specified, a 
value of 8 would be an index to the third long integer), or one of the following 


values: | 

Value Meaning 
GWL_EXSTYLE _ Extended window style 
GWL_STYLE Window style 


GWL_WNDPROC _ Long pointer to the window procedure 


The following values are also available when the hwnd parameter identifies a 


dialog box: | 
Value Meaning 7 
DWL_DLGPROC Specifies the address of the dialog box procedure. 
DWL_MSGRESULT Specifies the return value of a message processed in the 
dialog box procedure. 
DWL_USER _ Specifies extra information that is private to the applica- 
| tion, such as handles or pointers. . 
Return Value The return value specifies information about the given window if the function is 
successful. 
Comments To access any extra 4-byte values allocated when the window-class structure was 


created, use a positive byte offset as the index specified by the nOffset parameter, 
starting at O for the first 4-byte value in the extra space, 4 for the next 4-byte 
value, and so on. 


See Also GetWindowWord, SetWindowLong, SetWindow Word 
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GetWindowOrg 7 [ 2x | 


DWORD GetWindowOrg(hdc) 
HDC hdc; /* handle of device context i | 


The GetWindowOrg function retrieves the x- and y-coordinates of the origin of 
the window associated with the given device context. 


Parameters | hdc 
Identifies the device context. 


Return Value The low-order word of the return value contains the logical x-coordinate of the 
| window’s origin, if the function is successful; the high-order word contains the 
y-coordinate. 


Example The following example uses the GetWindowOrg function and the LOWORD 
and HTWORD macros to retrieve the x- and y-coordinates for the window origin: 


HDC hdc; 
DWORD dw; 
int xWindOrg, yWindOrg; 


hdc = GetDC(hwnd); 

dw GetWindowOrg(hdc); 
ReleaseDC(hwnd, hdc); 
xWindOrg = LOWORD(dw); 
yWindOrg = HIWORD(dw) ; 


See Also GetViewportOrg, SetWindowOrg 


GetWindowOrgEx " 3.1 | 


BOOL GetWindowOrgEx(hdc, [pPoint) 


HDC hdc; 

POINT FAR® [pPoint; 
This function retrieves the x- and y-coordinates of the origin of the window as- 
sociated with the specified device context. 

Parameters hdc 


Identifies the device context. 
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[pPoint 
Points to a POINT structure. The origin of the window (in logical coordinates) 
is placed in this structure. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


GetWindowPlacement [3.1 | 


BOOL GetWindowPlacement(hwnd, Ipwndpl) 
_ HWND hwnd; /* handle of window =) 
WINDOWPLACEMENT FAR*® Ipwndpl; /* address of structure for position data i 


The GetWindowPlacement function retrieves the show state and the normal 
(restored), minimized, and maximized positions of a window. 


Parameters hwnd 
Identifies the window. 


lpwndpl 
Points to the WINDOWPLACEMENT structure that receives the show state 
and position information. The WINDOWPLACEMENT structure has the fol- 


lowing form: 


typedef struct tagWINDOWPLACEMENT { /* wndpl */ 
UINT length; 
UINT flags; 
UINT showCmd; 
POINT ptMinPosition; 
POINT ptMaxPosition; 
RECT rcNormalPosition; 
} WINDOWPLACEMENT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also SetWindowPlacement 
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GetWindowRect ee Pax] 


void Get WindowReet(hwnd, Iprc) 
HWND hwnd; /* handle of window */ 
RECT FAR*® [prc; /* address of structure for window coordinates */ 


The GetWindowRect function retrieves the dimensions of the bounding rectangle 
of a given window. The dimensions are given in screen coordinates, relative to the 
upper-left corner of the display screen, and include the title bar, border, and scroll 
bars, if present. 


Parameters hwnd 
Identifies the window. 


pre 
Points to a RECT structure that receives the screen coordinates of the upper- 
left and lower-right corners of the window. The RECT structure has the follow- 
ing form: 


typedef struct tagRECT { /* ro */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 3 


Return Value This function does not return a value. 


Example | The following example calls the GetWindowRect function to retrieve the dimen- 
sions of the desktop window, and uses the dimensions to create a window that fills 
the right third of the desktop window: 


~ . RECT re; 
WORD wWidth; 


GetWindowRect(GetDesktopWindow(), &rc); 
/* Set the width to be 1/3 of the desktop window's width. */ 


wWidth = (rc.right - rce.left) / 3; 
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/* Create a main window for this application instance. */ 


hwndFrame = CreateWindow("MyClass", "My Title”, WS_OVERLAPPEDWINDOW, 


re.right - wWidth, /* horizontal position */ 
Q, /* vertical position  */ 
wWidth, /* width | * / 
rc.bottom, /* height * / 


(HWND) NULL, (HMENU) NULL, hinst, (LPSTR) NULL); 


See Also GetClientRect, MoveWindow, SetWindowPos 


GetWindowsDir 
#include <ver.h> | 


UINT GetWindowsDir(/pszAppDir, lpszPath, cbPath) 

LPCSTR [pszAppDir; /* address of Windows directory | 
LPSTR [pszPath; /* address of buffer for path a 
int cbPath; /* size of buffer for path */ 


The GetWindowsDir function retrieves the path of the Windows directory. This 
directory contains such files as Windows applications, initialization files, and help 
files. a | | 


GetWindowsDir is used by MS-DOS applications that set up Windows applica- 
tions; it exists only in the static-link version of the File Installation library. Win- 

dows applications should use the GetWindowsDirectory function to determine 

the Windows directory. | 


Parameters [pszAppDir 
Specifies the current directory in a search for Windows files. If the Windows 
directory is not on the path, the application must prompt the user for its location 
and pass that string to the GetWindowsDir function in the /pszAppDir parame- 
ter. 


lpszPath 
Points to the buffer that will receive the null-terminated string containing the 
path. | 

cbPath 7 he ee Pare 
Specifies the size, in bytes, of the buffer pointed to by the /pszPath parameter. 


Return Value The return value is the length of the string copied to the /pszPath parameter, in- 
7 _ cluding the terminating null character, if the function is successful. If the return 
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value is greater than the cbPath parameter, it is the size of the buffer required to 
_ hold the path. The return value is zero if the function fails. 


Comments The path that this function retrieves does not end with a backslash unless the 
Windows directory is the root directory. For example, if the Windows direc- 
tory is named WINDOWS on drive C, the path retrieved by this function is 
C:\WWINDOWS. If Windows is installed in the root directory of drive C, the path 
retrieved is C:\. 


After the GetWindowsDir function locates the Windows directory, it caches the 
location for use by subsequent calls to the function. 


See Also GetSystemDir, GetWindowsDirectory 


GetWindowsDirectory | 


UINT GetWindowsDirectory(ipszSysPath, cbSysPath) 
LPSTR /pszSysPath; /* address of buffer for Windows directory ig 
UINT cbSysPath; /* size of directory buffer 7) 


The GetWindowsDirectory function retrieves the path of the Windows directory. 
The Windows directory contains such files as Windows applications, initialization 
files, and help files. 


Parameters IpszSysPath — | 
Points to the buffer that will receive the null-terminated string containing the 
path. | 


cbSysPath 7 
Specifies the maximum size, in bytes, of the buffer. This value should be set to 
at least 144 to allow sufficient room in the buffer for the path. 


Return Value’ The return value is the length, in bytes, of the string copied to the lpszSysPath pa- 
: rameter, not including the terminating null character. If the return value is greater 
than the number specified in the cbSysPath parameter, it is the size of the buffer re- 
quired to hold the path. The return value is zero if the function fails. 


Comments | The Windows directory is the only directory where an application should create 
files. If the user is running a shared version of Windows, the Windows directory is 
the only directory guaranteed private to the user. 


The path this function retrieves does not end with a backslash unless the Windows 
directory is the root directory. For example, if the Windows directory is named 


Example 


See Also 
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WINDOWS on drive C, the path retrieved by this function is C\\WINDOWS. If 
Windows is installed in the root directory of drive C, the path retrieved is C:\. 


A similar function, GetWindowsDir, is intended for use by MS-DOS applications 
that set up Windows applications. Windows applications should use Get- 
WindowsDirectory, not GetWindowsDir. 


The following example uses the GetWindowsDirectory punen to determine the 
path of the Windows directory: 


WORD wReturn; 
char szBuf[144]; 


wReturn = GetWindowsDirectory((LPSTR)szBuf, sizeof(szBuf)); 
if (wReturn == @) 
MessageBox(hwnd, “function failed", 
rGetWindowsDirectory”, MB_ ICONEXCLAMATION) ; 
else if (wReturn > sizeof(szBuf)) 
MessageBox(hwnd, “buffer is too small”, 
| "GetWindowsDirectory”, MB_ICONEXCLAMATION); 


else : 
MessageBox(hwnd, szBuf, "GetWindowsDirectory", MB_OK); 


GetSystemDirectory 


GetWindowTask ote 


HTASK GetWindowTask(hwnd) 


HWND hwnd; 


| Parameters | 


Return Value 


See Also | 


/* handle of window */ 


~ The GetWindowTask function searches for the handle of a task associated with a | 


window. A task is any program that executes as an independent unit. All applica” 
tions are executed as tasks. Each instance of an application i is a task. 


| hwnd — 


Identifies the window for which to retrieve a task handle, ; 


The return value is the handle of the task associated with a particular window, if 
the function is successful. Otherwise, it is NULL. | 


EnumTaskWindows, GetCurrentTask = 
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GetWindowText Pax] 


int GetWindowText(hwnd, Ipsz, cbMax) 


HWND hwnd; __s/* handle of window | */ 
LPSTR Ipsz; /* address of buffer for text */ 
int chMax; /* maximum number of bytes to copy rh 


The GetWindowText function copies text of the given window’s title bar (if it has 
one) into a buffer. If the given window is a control, the text within the control is 
copied. 


Parameters hwnd 
Identifies the window or control containing the title bar or text. 
[psz 
Points to a buffer that will receive the title bar or text. 
cbMax | 
Specifies the maximum number of characters to copy to the buffer. The title bar 


or text is truncated if it is longer than the number of characters specified in 
cbMax. 


Return Value The return value specifies the length, in bytes, of the copied string, not including 
| the terminating null character. It is zero if the window has no title bar, the title bar 
is empty, or the hwnd parameter is invalid. 


~ Comments This function causes a WM_GETTEXT message to be sent to the given window 
or control. 
See Also GetWindowTextLength 


GetWindowTextLength _ i 


int GetWindowTextLength(iwnd) 
HWND hwnd; /* handle of window with text */ 


The GetWindowTextLength function retrieves the length, in bytes, of the text in ~ 
the given window’ title bar. If the window is a control, the length of the text 
within the control is retrieved. | 


Parameters hwnd 
Identifies the window or control. 
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ReturnValue = —-‘ The return value specifies the text length, in bytes, not including any null terminat- 
| ing character, if the function is successful. Otherwise, it is zero. 


Comments This function causes the WM_GETTEXTLENGTH message to be sent to the 
given window or control. 


~ See Also GetWindowText 


GetWindowWord Bx 


WORD GetWindowWord(hwnd, nOffset) 
HWND hwnd; /* handle of window i 
int nOffset; /* offset of value to retrieve 


The GetWindowWord function retrieves a word value at the specified offset into 
the extra window memory of the given window. Extra window memory is re- 
served by specifying a nonzero value in the cbWndExtra member of the 
'WNDCLASS structure used with the RegisterClass function. 


Parameters hwnd 
Identifies the window. 


nOffset 3 | 

Specifies the zero-based byte offset of the value to be retrieved. Valid values 

are in the range zero through the number of bytes of extra window memory, 
minus two (for example, if. 10 or more bytes of extra memory was specified, a. 
value of 8 would be an index to the fifth integer), or one of the following values: 


Value _ Meaning - , 
- GWW_HINSTANCE - Specifies the instance handle of the module that owns 
the window. 


~ GWW_HWNDPARENT Specifies the handle of the parent window, if any. The 
SetParent function changes the parent window of a 
~ child window. An application should not call the | 
-SetWindowWord function to ee the "parent of a 


: | . child window. 
GWW_ID Page, Specifies the identifier of the child window. 
Return Value | _ The return value specifies information about the given window if the function is 
7 successful. : a 
Comments ah To access any extra two-byte values allocated when the window-class structure 


‘was created, use a Pose byte offset as the index Species by the nOffset 
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See Also 


GetWinFlags 


parameter, starting at O for the first two-byte value in the extra space, 2 for the 
next two-byte value, and so on. 


GetWindowLong, SetParent, SetWindowLong, SetWindowWord 


DWORD Get WinFlags(void) 


Parameters 


Return Value 


Comments 


The GetWinF lags function retrieves the current Windows system and memory 
configuration. 


This function has no parameters. 


The return value specifies the current system and memory configuration if the 
function is successful. 


The configuration returned by GetWinFlags can be a combination of the follow- 
ing values: 


Value Meaning 

WF_80x87 System contains an Intel math coprocessor. 

WF_CPU086 System CPU is an 8086. Windows 3.1 will not return this flag. 
WF_CPU186 System CPU is an 80186. Windows 3.1 will not return this flag. 
WF_CPU286 System CPU is an 80286. 

WF_CPU386 System CPU is an 80386. 

WE_CPU486 System CPU is an i486. 


WF_ENHANCED Windows is running in 386-enhanced mode. The WF_PMODE 
flag is always set when WF_ENHANCED is set. 
WF_PAGING Windows is running on a system with paged memory. 
WF_PMODE Windows is running in protected mode. In Windows 3.1, this 
. flag is always set. 


WF_STANDARD Windows is running in standard mode. The WF_PMODE flag is 
always set when WF_STANDARD is set. 


~WF_WIN286 Same as WF_STANDARD. 


WF_WIN386 Same as WF_ENHANCED. 
WF_WLO Identifies an application running Windows-emulation libraries 


in a non-Windows operating system. 
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Example 


The following example uses the GetWinF lags function to display information 
about the current Windows system configuration: 


int len; 
char szBuf[80]; 
DWORD dwFlags; 


dwFlags = GetWinFlags(); 


len = sprintf (szBuf, “system 4S a coprocessor” 
(dwFlags & WF_80x87) ? “contains” : “does not contain"); 
TextOut(hdc, 10, 15, szBuf, len); | 


len = sprintf(szBuf, “processor is an %s", 
| (dwFlags & WF_CPU286) ? "80286" : 

(dwFlags & WF_CPU386) ? "80386" : 

(dwFlags & WF_CPU486) ? "i486" : "unknown"); 
TextOut(hdc, 10, 30, szBuf, len); 


len = sprintf(szBuf, "running in %S mode", 
(dwFlags & WF_ENHANCED) ? “enhanced” : “standard"™); 
TextOut(hdc, 10, 45, szBuf, len); — 


len = sprintf(szBuf, "%s WLO", : 
(dwFlags & WF_WLO) ? “using™ : “not using"); 
TextOut(hdc, 10, 60, szBuf, len); 


GetWinMem32Version = iets " a 


| #include <winmem32.h> . 


WORD Get WinMem32Version(void) 


Parameters — 


‘Return Value | 


The GetWinMem32Version function retrieves the application programming inter- 
face (API) version implemented by the WINMEM32.DLL dynamic- -link library. 
This is not the version number of the library itself. 


| This function has no parameters. 


| The return value specifies the version of the 32-bit memory API implemented by 


WINMEM32.DLL. The high-order 8 bits contain the major version number, and. 
the low- order 8 bits contain the minor version aummiber, 
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Global16PointerAlloc a 


#include <winmem32.h> 


WORD Global16PointerAlloc(wSelector, dwOffset, lpBuffer, dwSize, wFlags) 
*/ 


WORD w’Selector; /* selector of object 

DWORD dwOffset; /* offset of first byte for alias */ 

LPDWORD [pBuffer; —_—s/* address of location for alias st | 

DWORD dwSize; /* size ofregion _ */ 

WORD wFlags; /* reserved, must be zero */ 
The Global16PointerAlloc function converts a 16:32 pointer into a 16:16 pointer 
alias that the application can pass to a Windows function or to other 16:16 func- 
tions. — | 

Parameters wSelector 


Return Value 


Specifies the selector of the object for which an alias is to be sealed This must 
be the selector returned by a previous call to the Global32Alloc function. 


dwOffset 
Specifies the offset of the first byte for which an alias is to be created. The off- 
set is from the first byte of the object specified by the wSelector parameter. 
Note that wSelector.dwOffset forms a 16:32 address of the first byte of the re- 
gion for which an alias is to be created. 


lpBuffer 
Points to a four-byte location in memory that receives the 16:16 pointer alias 
for the specified region. 

dwSize — 
Specifies the addressable size, in bytes, of the region for which an alias is to be 
created. This value must be no larger than 64K. 


wFlags 
Reserved; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which can be one of the following: 


| WM532_Insufficient_Mem 


Comments — 


WM32_Insufficient_Sels 
WM32_Invalid_Arg 
WM32_Invalid_Flags 
WM32_ Invalid Func 


When this function returns successfully, the location pointed to by the [pBuffer pa- 
rameter contains a 16:16 pointer to the first byte of the region. This is the same 
byte to which wSelector.dwOffset points. 
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The returned selector identifies a descriptor for a data segment that has the follow- 
ing attributes: read-write, expand up, and small (B bit clear). The descriptor privi- 
lege level (DPL) and the granularity (the G bit) are set at the system’s discretion, 
so you should make no assumptions regarding their settings. The DPL and request- 
or privilege level (RPL) are appropriate for a Windows application. 


Note An application must not change the setting of any bits in the DPL or the RPL 
‘selector. Doing so can result in a system crash and will prevent the appucanen 
from running on compatible platforms. 


Because of tiling schemes implemented by some systems, the offset portion of the 
returned 16:16 pointer is not necessarily zero. 


When writing your application, you should not assume the size limit of the re- 


turned selector. Instead, assume that at least dwSize bytes can be addressed 
_ starting at the 16:16 pointer created by this function. 


See Also Global16PointerFree 


Global16PointerFree TT 
| #include <winmem32.h> : Em 


WORD Global16PointerFree(wSelector, dwAlias, wFlags) 


WORD wSelector; _/*selectorofobject = —s_ */ 
DWORD dwAlias;  /*pointeraliastofree = = */ 
WORD wFlags; /* reserved, must’ be zero +) 


The Global16PointerFree function frees the 16:16 pointer alias previously 
created by a call to the Global16PointerAlloc function. | 


Parameters | | wSelector — ae | 
Specifies the selector of the object for which the alias is to be freed. This must 
_ -be the selector returned my a previous call to the Global32Alloc function. 


dwAlias 
Specifies the 16:16 pointer alias to be freed. This must be the alias including a 
the original offset) returned ee a oe call to the Global! 6PointerAlloc : 
function. | 


wk lags 
Reserved; must be zero. 
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Return Value 


Comments 


See Also 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which can be one of the following: 


WMs32_Insufficient_Mem 
WMs32_Insufficient_Sels 
WMs32_Invalid_Arg 
WM32_Invalid_Flags 
WM32_Invalid_Func 


An application should free a 16:16 pointer alias as soon as it is no longer needed. 
Freeing the alias releases space in the descriptor table, a limited system resource. 


Global16PointerAlloc 


Global32Alloc | 


#include <winmem32.h> 


WORD Global32Alloc(dwSize, lpSelector, dwMaxSize, wFlags) 


DWORD dwSize; /* size of block to allocate */ 
LPWORD [pSelector; /* address of location for selector st 
DWORD dwMaxSize; /* maximum size of object */ 
WORD wFilags; /* sharing flag */ 


Parameters 


The Global32Alloc function allocates a memory object to be used as a 16:32 
(USE32) code or data segment and retrieves the selector portion of the 16:32 
address of the memory object. The first byte of the object is at offset 0 from this 
selector. 


dwSize 
Specifies the initial size, in bytes, of the object to be allocated. This value must 
be in the range 1 through ( 16 megabytes — 64K). 


_ [pSelector 


Points to a 2-byte location i in memory that receives the selector portion of the 
16:32 address of the allocated object. 


dwMaxSize 
Specifies the maximum size, in bytes, that the object will reach when it is reallo- 
cated by the Global32Realloc function. This value must be in the range 1 
through (16 megabytes — 64 K). If the application will never reallocate this 
memory object, the dwMaxSize parameter should be set to the same value as the 
dwSize parameter. 


Return Value 


Comments 


See Also — 
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wFlags 
Depends on the return value of the GetWinMem32Version function. If 
the return value is less than 0x0101, this parameter must be zero. If the 
return value is greater than or equal to 0x0101, this parameter can be set to 
GMEM_DDESHARE (to make the object shareable). Otherwise, this parame- 
_ ter should be zero. For more information about GMEM_DDESHARE, see the 
description of the GlobalAlloc function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which can be one of the following: 


WM32_Insufficient_. Mem 
WM32_Insufficient_Sels 
WM32_Invalid_Arg 
WM32_Invalid_Flags 
WM32_Invalid_Func 


If the Global32Alloc function fails, the value to which the /pSelector parameter 
points is zero. If the function succeeds, /pSelector points to the selector of the ob- 
ject. The valid range of offsets for the object referenced d by this selector is 0 
through (but not including) dwSize. 


In Windows 3.0 and later, the largest object that can be allocated is OxOOFFO000 


(16 megabytes — 64K). This is the limitation placed on WINMEM32.DLL by the 
current Windows kernel. 


The returned selector identifies a descriptor for a data segment that has the follow- 
ing attributes: read-write, expand-up, and big (B bit set). The descriptor privilege 
level (DPL) and the granularity (the G bit) are set at the system’s discretion, so 
you should make no assumptions regarding these settings. Because the system sets 
the granularity, the size of the object (and the selector size limit) may be greater 
than the requested size by up to 4095 bytes (4K minus 1). The DPL and requestor 
privilege level (RPL) will be appropriate for a Windows application. 


Note An application must not change the setting of any bits in the DPL or the RPL 
selector. Doing so can result in a system crash and will prevent the application 
from running on compatible platforms. 


The allocated object is neither movable nor discardable but can be paged. An appli- 
cation should not page-lock a 32-bit memory object. Page-locking an object is use- 
ful only if the object contains code or data that is used at interrupt time, and 32-bit 
memory cannot be used at interrupt time. | 


— Global32Free, Global32Realloc 
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Global32CodeAlias 


#include <winmem32.h> 


WORD Global32CodeAlias(wSelector, IpAlias, wFlags) 


WORD wSelector; /* selector of object for alias */ 
LPWORD IpAlias; —_—‘/* address of location for alias selector ig | 
~ WORD wFlags; /* reserved, must be zero | */ 


The Global32CodeAlias function creates a 16:32 (USE32) code-segment alias 
selector for a 32-bit memory object previously created by the Global32Alloc func- 
tion. This allows the application to execute code contained in the memory object. 


Parameters wSelector 
Specifies the selector of the object for which an alias is to be created. This must 
be the selector returned by a previous call to the Global32Alloc function. 


l[pAlias 
Points to a 2-byte location in memory that receives the selector portion of the | 
16:32 code-segment alias for the specified object. 


wFlags 
Reserved; must be zero. 


Return Value The return value is zero if the Anchen is successful. Otherwise, it is an error 
value, which can be one of the following: 


WM32_Insufficient_Mem 
WM32_Insufficient_Sels _ 
WM32_Invalid_Arg 
WM532_Invalid_Flags 
~WM32_ Invalid Func 


Comments If the function fails, the value pointed to by the /pAlias parameter is zero. If the 
function is successful, [pAlias points to a USE32 code-segment alias for the object 
specified by the wSelector parameter. The first byte of the object is at offset 0 
from the selector returned in IpAlias. Valid offsets are determined by the size of 
the object as set by the most recent call to the Global32Alloc or Global32Realloc 
function. | 


The returned selector identifies a descriptor for a code segment that has the follow- 
ing attributes: read-execute, nonconforming, and USE32 (D bit set). The descrip- 
tor privilege level (DPL) and the granularity (the G bit) are set at the system’s 
discretion, so you should make no assumptions regarding their settings. The granu- 
larity will be consistent with the current data selector for the object. The DPL and 
requestor privilege level (RPL) are appropriate for a Windows application. 
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Note An application must not change the setting of any bits in the DPL or the RPL 
selector. Doing so can result in a system crash and will pieve the application 
from running on compatible platforms. 


An application should not call this function more than once for an object. Depend- 
ing on the system, the function might fail if an application calls it a second time 
for a given object without first calling the Global32CodeAliasFree function for 
the object. 


See Also Global32Alloc, Global32CodeAliasFree 


Global32CodeAliasFree 


#include <winmem32.h> 


WORD Global32CodeAliasFree(wSelector, wAlias, wFlags) 
WORD wsSelector; /* selector of object 

WORD WAlias; /* code-segment alias selector to free */ 
WORD wFlags; /* reserved, must be zero | */ 


The Global32CodeAliasFree function frees the 16:32 (USE32) code-segment 
alias selector previously created by a call to the Global32CodeAlias function. 


Parameters wSelector 
Specifies the selector of the object for which the alias is to be freed. This must 
__ be the selector returned by a ee call to the Global32Alloc function. 


wAlias 
Specifies the USE32 code-segment alias selector to be freed. This must be the 
alias returned by a previous call to the Global32CodeAlias function. 


wFlags 
Reserved; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
| | value, which can be one of the following: 


WM32_Insufficient_Mem 
WM32_Insufficient_Sels 
WM32_Invalid_Arg 
WM32_Invalid_Flags 
WMs32_Invalid_Func 


See Also Global32CodeAlias 
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Global32Free 


#include <winmem32.h> 


WORD Global32Free(wSelector, wFlags) 


WORD w’Selector; 


WORD wFlags; 


Parameters 


Return Value 


Comments 


See Also 


/* selector of object to free sa 
/* reserved, must be zeros **/ 


The Global32Free function frees an object cus allocated by the 
Global32Alloc function. 


wSelector 
Specifies the selector of the object to be freed. This must be the selector re- 
turned by a previous call to the Global32Alloc function. 


wFlags 
Reserved; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which can be one of the following: 


WM32_Insufficient_Mem 
WM32_Insufficient_Sels 
WM32_Invalid_Arg 
WM32_Invalid_Flags 
WM32_Invalid_ Func 


The Global32Alloc function frees the object itself; it also frees all aliases created 
for the object by the 32-bit memory application programming interface (API). 


Note Before terminating, an application must call this function to free each object 


allocated by the Global32Alloc function to ensure that all aliases created for the 
object are freed. 


Global32Alloc, Global32Realloc 
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Global32Realloc 


#include <winmem32.h> 


WORD Global32Realloc(wSelector, dwNewSize, wFlags) 


WORD wSelector; /* selector of object to reallocate */ 

DWORD dwNewSize; /* new size of object *] 

WORD wFilags; /* reserved, must be zero — a 
The Global32Realloc function changes the size of a 32-bit memory object pre- 
viously allocated by the Global32Alloc function. 

Parameters wSelector 


Return Value 


Comments 


Specifies the selector of the object to be changed. This must be the selector re- 
turned by a previous call to the Global32Alloc function. 


dwNewSize 
Specifies the new size, in bytes, of the object. This value must be greater than 
zero and less than or equal to the size specified by the dwMaxSize parameter of 
the Global32Alloc function call that created the object. 


wFlags 
Reserved; must be zero. — 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which can be one of - following: 


WM32_Insufficient_Mem 
WM32_Insufficient_Sels 
WM32_Invalid_Arg 
WM32_Invalid_Flags — 
WM32_Invalid_Func 


If this function fails, the previous state of the object is unchanged. If the function 
succeeds, it updates the state of the object and the state of all aliases to the object 
created by the 32-bit memory application programming interface (API) functions. 
For this reason, an application must call the the Global32Realloc function to 
change the size of the object. Using other Windows functions to manipulate the ob- 
ject results in corrupted aliases. 


This function does not change the selector specified by the wSelector parameter. If 
this function succeeds, the new valid range of offsets for the selector is zero 
through (but not including) dwNewSize. 
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The system determines the appropriate granularity of the object. As a result, the 
size of the object (and the selector size limit) may be greater than the requested 
size by up to 4095 bytes (4K minus 1). 


See Also — Global32Alloc, Global32Free 


GlobalAddAtom 2x | 


ATOM GlobalAddAtom(/pszString) 
LPCSTR [pszString; /* address of string to add */ 


The GlobalAddAtom function adds a string to the system atom table and returns 
a unique value identifying the string. 


Parameters IpszString 
Points to the null-terminated string to be added. The case of the first string 
added is preserved and returned by the GlobalGetAtomName function. Strings 
that differ only in case are considered identical. 


Return Value _ The return value identifies the string if the function is successful. Otherwise, it is 
zero. 
Comments If the string exists already in the system atom table, the atom for the existing string 


will be returned and the atom’s reference count will be incremented (increased by 
one). The string associated with the atom will not be deleted from memory until its 
reference count is zero. For more information, see the description of the Global- 
DeleteAtom function. 


Global atoms are not deleted automatically when the application terminates. For 
every call to the GlobalAddAtom function, there must be a corresponding call to 
the GlobalDeleteAtom function. 


Exa mple The following example adds the string “This is a global atom” to the system atom 
table: | 


_ ATOM atom; 
char szMsg[80]; 


atom = GlobalAddAtom("This is a global atom"); 
if (atom == Q@) 


MessageBox(hwnd, "GlobalAddAtom failed", "", 
MB_ICONSTOP); 
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else { 
wsprintf(szMsg, "GlobalAddAtom returned %u", atom); 
MessageBox(hwnd, szMsg, "", MB_OK); | 


See Also 2 AddAtom, GlobalDeleteAtom, GlobalGetAtomName | 


GlobalAlloc — [2x | 


HGLOBAL GlobalAlloc(fuAlloc, cbAlloc) 


UINT fuAlloc; /* how to allocate object = */ 
DWORD cDAlloc; /* size of object — */ 
The GlobalAlloc function allocates the specified number of bytes oid the global 
heap. 
Parameters fuAlloc 
Specifies how to allocate meer This parameter can ee a combination of the 
following values: 
Value | Meaning | , 
GHND Be Combines the GMEM_MOVEABLE and 
GMEM_ZEROINIT flags. 
GMEM_DDESHARE Allocates sharable memory. This flag is used for dy- 


- namic data exchange (DDE) only. This flag is equiv- 
alent to GMEM_SHARE. 


~GMEM_DISCARDABLE Allocates discardable memory. This flag can only be 
used with the GMEM_MOVEABLE flag. 


GMEM_FIXED Allocates fixed memory. The GMEM_FIXED and 
GMEM_MOVEABLE flags cannot be combined. 

GMEM_LOWER Same as GMEM_NOT_BANKED. This flag is ig- 

7 | nored in Windows 3.1. 
GMEM_MOVEABLE Allocates movable memory. The GMEM_FIXED | 
and GMEM_MOVEABLE flags cannot be combined. 

GMEM_NOCOMPACT Does not compact or discard memory to saree the al- 
location request. 

GMEM_NODISCARD Does not discard memory to satisfy the Ailscdtion re- 
quest. 


GMEM_NOT_BANKED Allocates non-banked memory (memory is not 
‘ within the memory provided by expanded memory). 
This flag cannot be used with the GMEM_NOTIFY 
flag. This flag is ignored in Windows 3.1. 
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Return Value 


- Comments 


Example 


Value | Meaning 

GMEM_N OTIFY | Calls the notification routine if the memory object is 
discarded. | 

GMEM_SHARE Allocates memory that can be shared with 


other applications. This flag is eAuvatent to 
GMEM_DDESHARE. 


GMEM_ZEROINIT Initializes memory contents to zero. 


GPTR Combines the GMEM_FIXED and 
GMEM_ZEROINIT flags. 


cbAlloc 
Specifies the number of bytes to be allocated. 


The return value is the handle of the newly allocated global memory object, if the 
function is successful. Otherwise, it is NULL. 


To convert the handle returned by the GlobalAlloc function into a pointer, an ap- 


plication should use the GlobalLock function. 


If this function is successful, it allocates at least the amount requested. If the 
amount allocated is greater than the amount requested, the application can use the 
entire amount. To determine the size of a global memory object, an application 
can use the GlobalSize function. | | 


To free a global memory object, an application should use the GlobalFree func- 


tion. To change the size or attributes of an allocated memory object, an application 
can use the GlobalReAlloc function. 


The largest memory object that an application can allocate on an 80286 processor 
is 1 megabyte less 80 bytes. The largest block on an 80386 processor is 16 mega- 
bytes less 64K. 


If the cbAlloc parameter is zero, the GlobalAlloc function returns a handle of a 
memory object that is marked as discarded. 


The following example uses the GlobalAlloc and GlobalLock functions to 


allocate memory, and then calls the GlobalUnlock and GlobalFree functions 


to free it. 


See Also 


GlobalCompact $499 
HGLOBAL hg1b; 
void FAR* lpvBuffer; 


hglb = GlobalAlloc(GPTR, 1024); 
lpvBuffer = GlobalLock(hglb) ; 


GlobalUnlock(hglb); 
Global Free(hglb); 


GlobalFree, GlobalLock, GlobalNotify, GlobalReAlloc, GlobalSize, 
LocalAlloc 


GlobalCompact * "eels ean| 


DWORD GlobalCompact(dwM inF ree) 
~ DWORD dwMinFree; /* amount of memory requested i | 


Parameters | 


Return Value 


— Comments 


-— $ee Also 


The GlobalCompact function rearranges memory currently allocated to the global 
heap so that the specified amount of memory is free. If the function cannot free the 


_ requested amount of memory, it frees as much as possible. 


dwMinFree 
Specifies the number of contiguous free bytes desired. If this parameter is zero, 
the function does not discard memory, but the return value is valid. 


The return value specifies the number of bytes in the largest free global memory _ 
object in the global heap. If the dwMinFree parameter is zero, the return value 
specifies the number of bytes in the largest free object that Windows can generate 
if it removes all discardable ee 


If an application passes the return value to the GlobalAlloc function, the 
GMEM_NOCOMPACT or GMEM_NODISCARD flag should not be used. 


This function always rearranges movable memory objects before checking for free 
memory. Then it checks the memory currently allocated to the global heap for the 


- number of contiguous free bytes specified by the dwMinF ree parameter. If the _ 
‘specified amount of memory is not available, the function discards unlocked dis- 


cardable objects, until the requested spaces 1S S generated (if possible). 
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GlobalDeleteAtom | [ 2.x | 


ATOM GlobalDeleteAtom(atm) 
ATOM aim; /* atom to delete | a | 


The GlobalDeleteAtom function decrements (decreases by one) the reference 


count of a global atom. If the atom’s reference count reaches zero, the string as- 
sociated with the atom is removed from the system atom table. 


Parameters atm 
Identifies the atom to be deleted. 


Return Value The return value is zero if the function is successful. The return value is equal to 


the atm parameter if the function failed to decrement the reference count for the 
specified atom. 
Comments An atom’s reference count specifies the number of times the string has been added 


to the atom table. The GlobalAddAtom function increments (increases by one) 
the reference count each time it is called with a string that already exists in the sys- 
tem atom table. 


The only way to ensure that an atom has been deleted from the atom table is to call 
this function repeatedly until it fails. When the count is decremented to zero, the 
next GlobalFindAtom or GlobalDeleteAtom function call will fail. 


Example The following example repeatedly calls the GlobalDeleteAtom function to decre- 
ment the reference count for the atom until the atom is deleted and the Global- 
DeleteAtom function does not return zero: 


int cRef; 
ATOM atom; 
char szMsg[80]; 


for (cRef = @; ((atom = GlobalFindAtom("This is a global atom")) != @); 
cRef++) | 
~GlobalDeleteAtom(atom) ; 


wsprintf(szMsg, “reference count was 4d", cRef); 
MessageBox(hwnd, szMsg, "GlobalDeleteAtom", MB_OK); 


See Also DeleteAtom, GlobalAddAtom, GlobalFindAtom 


GlobalDosFree 501 


GlobalDosAlloc a | 


~DWORD GlobalDosAlloc(cbAlloc) 
DWORD cbAlloc; /* number of bytes to allocate | 


The GlobalDosAlloc function allocates global memory that can be accessed by 
MS-DOS running in real mode. The memory is guaranteed to exist in the first meg- 
abyte of linear address space. 


An application should not use this function unless it is absolutely necessary, be- 
_ cause the memory pool from which the object is allocated is a scarce system re- 
source. | 


Parameters cbAlloc 
Specifies the number of bytes to be allocated. 


Return Value - The return value contains a paragraph-segment value in its high-order word and a 
selector in its low-order word. An application can use the paragraph-segment — 
value to access memory in real mode and the selector to access memory in pro- 
tected mode. If Windows cannot allocate a block of memory of the requested size, 
the return value is zero. 


Comments Memory allocated by using the GlobalDosAlloc function does not need to be 
| locked pa using the GlobalLock function. 


See Also | GlobalDosFree 


GlobalDosFree 
UINT GlobalDosFree(uSelector) 


UINT uSelector; /* memory to free */ 


The GlobalDosFree function frees a global memory object paul) allocated 
by the GlobalDosAlloc function. 


Parameters Selector | . 
Pairs ii Identifies the memory object to be freed. 
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Return Value The return value is zero if the function is successful. Otherwise, it is equal to the 
uSelector parameter. | 
See Also GlobalDosAlloc 


GlobalEntryHandle [3.1 | 


_ #include <toolhelp.h> 


BOOL GlobalEntryHandle(/pge, hglb) 
GLOBALENTRY FAR* Ipge;_-_—s/* address of structure for object */ 
HGLOBAL heglb; /* handle of item i 


The GlobalEntryHandle function fills the specified structure with information 
that describes the given global memory object. 


Parameters Ipge 
| Points to a GLOBALENTRY structure that receives information about the 
global memory object. The GLOBALENTRY structure has the following 


form: : 
#Finclude <toolhelp.h> 


typedef struct tagGLOBALENTRY { /* ge */ 

DWORD dwSize; 
-DWORD ~~ dwAddress; 

DWORD dwBlockSize; 
HGLOBAL hBlock; 
WORD wcLock; 
WORD wcPageLock; 
WORD wFlags; 
BOOL wHeapPresent; 
HGLOBAL hOQwner; 
WORD wlype; 
WORD wData; 
DWORD dwNext; 
DWORD dwNextAlt; 

} GLOBALENTRY; 


For a full description of this structure, see the M. icrosoft Windows Program- 
mer’s Reference, Volume 3. 
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hglb 
Identifies the global memory object to be described. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. The 
function fails if the hglb value is an invalid handle or selector. 


Comments This function retrieves information about a global memory handle or selector. De- 
buggers use this function to obtain the segment number of a segment loaded from 
an executable file. 


Before calling the GlobalEntryHandle function, an application must initialize the 
GLOBALENTRY structure and specify its size, in bytes, in the dwSize member. 


See Also GlobalEntryModule, GlobalFirst, GlobalInfo, GlobalNext 


GlobalEntryModule = a 


#include <toolhelp.h> | 

BOOL GlobalEntryModule(ipge, hmod, wSeg) 7 | , 
GLOBALENTRY FAR*® Ipge; [* address of structure for segment cou 
HMODULE hmod; _ /* handle of module el) 
WORD wSeg; : /* segment to describe _ ua 


The GlobalEntry Module function fills the specie’: structure by pee with Inter: 
mation about the specified module segment. 


Parameters Joe 
Points to a GLOBALENTRY structure that receives information about the seg- 
ment specified in the wSeg parameter. The GLOBALENTRY. structure has the 
following form: . | 


#include <toolhelp.h> 


typedet struct tagGLOBALENTRY i: /* ge */ 
DWORD dwSize; | 
DWORD dwAddress; 
DWORD dwBlockSize; 
HGLOBAL hBlock; 
WORD ~~ _—-wcLock; 
WORD ~=wcPageLock; 
WORD ~—_—iwFilags; 
BOOL = wHeapPresent; 
HGLOBAL hOwner; 
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WORD wlype; 

WORD wData; 

DWORD dwNext; 

DWORD dwNextAlt; 
} GLOBALENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hmod 
Identifies the module that owns the segment. 


wSeg 
Specifies the segment to be described in the GLOBALENTRY structure. The 
number of the first segment in the module is 1. Segment numbers are always 
contiguous, so if the last valid segment number is 10, all segment numbers 1 
through 10 are also valid. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. This 
| function fails if the segment in the wSeg parameter does not exist in the module 
specified in the hmod parameter. 


Comments Debuggers can use the GlobalEntry Module function to retrieve global heap infor- 
mation about a specific segment loaded from an executable file. Typically, the de- 
bugger will have symbols that refer to segment numbers; this function translates 
the segment numbers to heap information. — 


Before calling GlobalEntryModule, an application must initialize the 
~ GLOBALENTRY structure and specify its size, in bytes, in the dwSize member. 


See Also GlobalEntryHandle, GlobalFirst, GlobalInfo, GlobalNext 


GlobalFindAtom 2x | 


ATOM GlobalFindAtom(IpszString) 
LPCSTR [pszString; /* address of string to find =) 


The GlobalFindAtom function searches the system atom table for the specified 
character string and retrieves the global atom associated with that string. (A global 
atom is an atom that is available to all Windows applications.) 


Parameters IpszString 
Points to the null-terminated character string to search for. 


Return Value 


Example 


See Also 


- GlobalFirst 
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The return value identifies the global atom associated with the given string, if the 
function is successful. Otherwise, if the string is not in the table, the return value is 
zero. 


The following example repeatedly calls the GlobalFindAtom function to retrieve 
the atom associated with the string “This is a global atom”. The example uses the 
GlobalDeleteAtom function to decrement (decrease by one) the reference count 
for the atom until the atom is deleted and GlobalFindAtom returns zero. 


int cRef; 
ATOM atom; 
char szMsg[80]; 


for (cRef = @; ((atom = GlobalFindAtom("This is a global atom")) != @); 
cRef++) oe 
GlobalDeleteAtom(atom) ; 


wsprintf(szMsqg, "reference count was 4d", cRef); 
MessageBox(hwnd, szMsg, "GlobalDeleteAtom", MB_OK); 


FindAtom, GlobalAddAtom, GlobalDeleteAtom 


#include <toolhelp. h>— 

BOOL GlobalFirst(Ipge, wFlags) | 
GLOBALENTRY FAR*® [pge; /* address of structure for object gs 
WORD wFilags; /* specifies the heap to use =) 


Parameters 


The GlobalFirst function fills the specified structure with information that de- 


scribes the first object on the global heap. 


lpge 
Points toa GLOBALENTRY structure that receives ¢ information about the 
global memory object. The GLOBALENTRY structure has the pollowate 
form: 


#include écooihel p: h> 


typedef struct tagGLOBALENTRY { a ge / 
| DWORD  dwSize; 
DWORD dwAddress; 
- DWORD = dwBlockSize; | nas 
HGLOBAL hBlock; ae 
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WORD ~wcLock; 
WORD wcPageLock; 
WORD wFlags; 
BOOL wHeapPresent; 
HGLOBAL hOwner; 
WORD wlype; 
WORD wData; 
DWORD dwNext; 
DWORD dwNextAlt; 
} GLOBALENTRY; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


wFlags 
Specifies the heap to use. This parameter can be one of the following values: 
Value > Meaning | 
GLOBAL_ALL Structure pointed to by lpge will receive information about the 


first object on the complete global heap. 


GLOBAL_FREE ___ Structure will receive information about the first object on the 
free list. 


GLOBAL_LRU Structure will receive information about the first object on the 
least-recently-used (LRU) list. 


‘Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The GlobalFirst function can be used to begin a global heap walk. An application 
can examine subsequent objects on the global heap by using the GlobalNext func- 
tion. Calls to GlobalNext must have the same wFlags value as that specified in 
GlobalFirst. 


Before calling GlobalFirst, an application must initialize the GLOBALENTRY 
structure and specify its size, in bytes, in the dwSize member. 


See Also _ GlobalEntryHandle, GlobalEntryModule, GlobalInfo, GlobalNext 


GlobalFix | 


void GlobalFix(hglb) - | 
HGLOBAL hgib; —_—s/* handle of object to fix ad 


The GlobalFix cuneton preveuls the given global memory 0b) ect from moving in 
linear memory. 
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This function interferes with effective Windows memory management and can re- 
sult in linear-address fragmentation. Few applications need to fix memory in linear 
address space. 


Parameters hglb 
Identifies the global memory object to be fixed in linear memory. 


Return Value This function does not return a value. 


Comments The object is locked into linear memory at its current address, and its lock count is 
incremented (increased by one). Locked memory is not subject to moving or dis- 
carding except when the memory object is being reallocated by the Global- 
ReAlloc function. The object remains locked in memory until its lock count is 
decreased to zero. 


Each time an application calls the GlobalFix function for a memory object, it 
must eventually call the GlobalUnfix function, which decrements (decreases by 
one) the lock count for the object. Other functions also can affect the lock count of 
a memory object. For a list of these functions, see the description of the Global- 
Flags function. 


See Also GlobalFlags, GlobalReAlloc, GlobalUnfix 


GlobalFlags oe, ax] 
UINT GlobalFlags(hg/b) | 
HGLOBAL hglb; /* handle of global memory object **/ 


The GlobalFlags function returns information about the given global memory ob- 
ject. | 


Parameters © —hgilb 
: Identifies the global memory object. 


Return Value The return value specifies the memory-allocation flag and the lock count for the 
memory object, if the function is successful. 


Comments When an application masks out the lock count in the low-order byte of the return 
value, the return value contains one of the nO OwinE allocation flags: 
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See Also 


Value | Meaning 
GMEM_DISCARDABLE Object can be discarded. 
GMEM_DISCARDED Object has been discarded. 


The low-order byte of the return value contains the lock count of the object. Use 
the GMEM_LOCKCOUNT mask to retrieve the lock count from the return value. 


The following functions can affect the lock count of a global memory object: 


Increments lock count Decrements lock count 
GlobalFix GlobalUnfix 
GlobalLock GlobalUnlock 


GlobalFix, GlobalLock, GlobalUnfix, GlobalUnlock 


GlobalFree 


pers 


HGLOBAL GlobalFree(hg/b) 


HGLOBAL hegib; 


Parameters 
Return Value 


Comments 


See Also 


/* handle of object to free of 


The GlobalF ree function frees the given global memory object (if the object is not 
locked) and invalidates its handle. 


hglb 
Identifies the global memory object to be freed. 


The return value is NULL if the function is successful. Otherwise, it is equal to the 
hglb parameter. 


The GlobalF ree function cannot be used to free a locked memory object—that is, 
a memory object with a lock count greater than zero. For a list of the functions that 
affect the lock count, see the description of the GlobalFlags function. 


Once freed, the handle of the memory object must not be used again. Attempting 
to free the same memory object more than once can cause Windows to terminate 


| anomaly: 


| GlobalDiscard, GlobalFlags, GlobalLock 
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GlobalGetAtomName [2x | 


UINT GlobalGetAtomName(atom, lpszBuffer, cbBuffer) 


ATOM atom; 
LPSTR IpszBuffer; 
int cbBuffer; 


Parameters 


Return Value 


Example 


/* atom identifier ** / 
/* address of buffer for atom string *] 
/* size of buffer ** / 


The GlobalGetAtomName function retrieves a copy of the character string as- 
sociated with the given global atom. (A global atom is an atom that is available to 
all Windows applications.) 


atom 7 
Identifies the global atom associated with the character string to be retrieved. 


lpszBuffer 
Points to the buffer for the character string. 


cbBuffer 
Specifies the size, in bytes, of the buffer. 


The return value specifies the number of bytes copied to the buffer, not including 
the terminating null character, if the function is successful. 


The following example uses the GlobalGetAtomName function to retrieve the 
character string associated with a global atom: | 


char szBuf[8Q]; 
GlobalGetAtomName(atGlobal, szBuf, sizeof(szBuf)); 


MessageBox(hwnd, szBuf, "GlobalGetAtomName", MB OK); 


GlobalHandle | : 


DWORD GlobalHandle(uGlobalSel) 


UINT uGlobalSel; 


Parameters 


/* selector of global memory object i 


The GlobalHandle function retrieves the handle of the specified global memory 
object. 


uGlobalSel 
Specifies the selector of a global memory object. 
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Return Value The low-order word of the return value contains the handle of the global memory _ 
object, and the high-order word contains the selector of the memory object, if the — 
function is successful. The return value is NULL if no handle exists for the 
memory object. 


GlobalHandleToSel . [ 3.1 | 


#include <toolhelp.h> 
WORD GlobalHandleToSel(hglb) 


HGLOBAL hglb; 

The GlobalHandleToSel function converts the given handle to a selector. 

Parameters hglb : 

Identifies the global memory object to be converted. 

Return Value The return value is the selector of the given object if the function is successful. 
Otherwise, it is zero. 

Comments — The GlobalHandleToSel function converts a global handle to a selector appro- 
priate for Windows, version 3.0 or 3.1, depending on which version is running. A 
debugging application might use this selector to access a global memory object if 
the object is not discardable or if the object’s attributes are irrelevant. 

See Also GlobalAlloc 


Globalinfo ely 


_#include <toolhelp.h> 


BOOL GlobalInfo(/pgi) | 
GLOBALINFO FAR* Ipgi;_——s/* address of global-heap structure § */ 


The GlobalInfo function fills the specified structure with information that de- 
scribes the global heap. 
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Parameters Ipgi 
| Points to a GLOBALINFO structure that receives information about the global 
heap. The GLOBALINFO structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagGLOBALINFO { /* gi */ 
DWORD dwSize; 
WORD wclItems; 
WORD wclItemsFree; 
WORD wclItemsLRU; 
} GLOBALINFO; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value ~ The return value is nonzero if the function successful. Otherwise, it is zero. 


Comments The information in the structure can be used to determine how much memory to al- 
7 locate for a global heap walk. 


Before calling the GlobalInfo function, an application must initialize the 
GLOBALINFO structure and specify its size, in bytes, in the dwSize member. _ 


See Also GlobalEntryHandle, GlobalEntryModule, GlobalFirst, GlobalNext 


GlobalLock Pex | 


void FAR* GlobalLock(hglb) 
HGLOBAL hglb; /* handle of memory object to lock **/ 


The GlobalLock function returns a pointer to the given global memory object. 
GlobalLock increments (increases by one) the lock count of movable objects and 
locks the memory. Locked memory will not be moved or discarded unless the 
memory object is reallocated by the GlobalReAlloc function. The object remains 
locked in memory until its lock count is decreased to zero. 


Parameters hglb 
‘Identifies the global memory object to be locked. 


Return Value The return value points to the first byte of memory in the global object, if the func- 
| tion is successful. It is NULL if the object has been discarded or an error occurs. 


512 GlobalLRUNewest 


Comments _ Each time an application calls the GlobalLock fanedion for an object, it must even- 
tually call the GlobalUnlock function for the object. 


This function will return NULL if an application attempts to lock a memory ours 
with a zero-byte size. 


If GlobalLock incremented the lock count for the object, GlobalUnlock decre- 
ments the lock count for the object. Other functions can also affect the lock count 
of a memory object. For a list of these functions, see the description of the Get- 
GlobalF lags function. 


Discarded objects always have a lock count of zero. 


See Also GlobalFlags, GlobalReAlloc, GlobalUnlock 


GlobalLRUNewest ex] 


HGLOBAL GlobalLRUNewest(hglb) 
HGLOBAL heglb; /* handle of memory object to move sa | 


The GlobalLRUNewest function moves a global memory object to the newest 
least-recently-used (LRU) position in memory. This greatly reduces the likelihood 
that the object will be discarded soon, but does not prevent the object from eventu- 
ally being discarded. 


Parameters hglb 
| Identifies the global memory object to be moved. 


Return Value The return value is NULL if the hglb parameter is not a valid handle. 
Comments ~The GlobalLRUNewest function is useful only if the given object is discardable. 


See Also GlobalLRUOldest 
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GlobalLRUOlIdest : 2x] 


HGLOBAL GlobalLRUOldest(hg/b) | 
HGLOBAL heglb; /* handle of memory object to move */ 


The GlobalLRUOldest function moves a global memory object to the oldest least- 
recently-used (LRU) position in memory. This makes the memory object the next 
candidate for discarding. | 


Parameters hgelb | 


Identifies the global memory object to be moved. 
Return Value The return value is NULL if the hg/b parameter does not identify a valid handle. 
| Comments The GlobalLRUOldest function is useful only if the hglb object is discardable. 
See Also -. GlobalLRUNewest 


GlobalNext xy 


#include <toolhelp.h>~ 


BOOL GlobalNext(/pge, flags) 
GLOBALENTRY FAR? /pge; /* address of structure for object ee 
WORD flags; /* heap to use iy 


_ The GlobalNext function fills the specified structure with information that de- 
scribes the next object on the global heap. | 


Parameters . _—_Ipge | ae 
Points to a GLOBALENTRY structure that receives information about the 
global memory object. The GLOBALENTRY structure has the following 
form: | 


#include <toolhelp.h> 


typedef struct tagGLOBALENTRY { /* ge */ 
DWORD dwSize; oe" 
DWORD  dwAddress; 
DWORD dwBlockSize; 
HGLOBAL hBlock; 
WORD wcLock; 
WORD. = wcPageLock; 


514 GlobalNotify | 


WORD wFlags; 

BOOL wHeapPresent; 
HGLOBAL hOwner; 

WORD wlype; 

WORD wData; 

DWORD =~ dwNext; 

DWORD dwNextAlt; 

— GLOBALENTRY ; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


flags | 
Specifies heap to use. This parameter can be one of the following values: 


Value — Meaning 
GLOBAL_ALL Structure pointed by the /pge parameter will receive informa- 
tion about the first object on the complete global heap. 


GLOBAL_FREE Structure will receive information about the first Onis! on the 
free list. 


GLOBAL_LRU Structure will receive information about the first object on the 
least-recently-used (LRU) list. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The GlobalNext function can be used to continue a global heap walk started by 
| the GlobalFirst, GlobalEntryHandle, or GlobalEntryModule functions. 


If GlobalFirst starts a heap walk, the flags value used in GlobalNext must be the 
same as the value used in GlobalFirst. | 


See Also -GlobalEntryHandle, GlobalEntryModule, GlobalFirst, GlobalInfo 


GlobalNotify ° Sis 4, aut eae 


void GlobalNotify(ipNotifyProc) - 
GNOTIFYPROC IpNotifyProc; —_—‘/* instance address of callback function */ 


The GlobalNotify function installs a notification procedure for the current task. A 
notification procedure is a library-defined callback function that the system calls 

whenever a global memory object allocated with the GMEM_ NOTIFY flag is 
about to be discarded. 


Parameters | 


Return Value 


Comments 


See Also | 
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lpNotifyProc 
Specifies the address of the current task’s notification procedure. For more in- 
formation, see the description of the NotifyProc callback function. 


This function does not return a value. 


An application must not call the GlobalNotify function more than once per in- 
stance. 


The system does not call the notification procedure when discarding memory that 
belongs to a dynamic-link library (DLL). 


If the object is discarded, the application must use the GMEM_NOTIFY flag 
when it calls the GlobalRealloc function to recreate the object. Otherwise, the ap- 


plication will not be notified when the object is discarded again. 


_ If the notification procedure returns a nonzero Gale Windows discus the global 


memory object. If the procedure returns zero, the block is not discarded. 


The address of the NotifyProc callback function (specified in the IpNotifyProc pa- 
rameter) must be in a fixed code segment of a dynamic-link library. 


GlobalReAlloc, NotifyProc 


GlobalPageLock og os ESTs 


UINT GlobalPageLock(hg/lb) 


HGLOBAL hgib; 


Parameters 
‘Return Value | 


Comments oe 


| hglb 


/* selector of global memory to lock */ 


The GlobalPageLock function increments (increases by one) the page-lock count 
for the memory associated with the given global selector. As long as its page- -lock 


count is nonzero, the data that the selector references is guaranteed to remain in 
_ memory at the same physical address. | 


Specifies: the selector of the memory to be page- ‘locked: 


The return value specifies the page-lock count after the function has incremented 


it. If the function fails, the return value 1 is Zero. 


Because using this fanction violates pieferted Windows programming practices, 
an application should not use it unless absolutely necessary. The function is 
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intended to be used for dynamically allocated data that must be accessed at inter- 
rupt time. For this reason, it must be called only from a dynamic-link library | 
(DLL). | 


The GlobalPageLock function increments the page-lock count for the block of 
memory, and the GlobalPageUnlock function decrements (decreases by one) the 
page-lock count. Page-locking operations can be nested, but each page-locking 
must be balanced by a corresponding unlocking. 


See Also GlobalPageUnlock 


GlobalPageUnlock 


UINT GlobalPageUnlock(hglb) 
HGLOBAL hglb; /* selector of global memory to unlock +] 


The GlobalPageLock function decrements (decreases by one) the page-lock count 
for the memory associated with the specified global selector. When the page-lock 
count reaches zero, the data that the selector references is no longer guaranteed to 
remain in memory at the same physical address. 


Parameters hglb 3 
Specifies the selector of the memory to be page-unlocked. 


Return Value The return value specifies the page-lock count after the function has decremented 
it. If the function fails, the return value is zero. 


Comments Because using this function violates preferred Windows programming practices, 
an application should not use it unless absolutely necessary. The function is in- 
tended to be used for dynamically allocated data that must be accessed at interrupt 
time. For this reason, it must only be called from a dynamic-link library (DLL). 


The GlobalPageLock function increments the page-lock count for the block of 
memory, and the GlobalPageUnlock function decrements the page-lock count. 
Page-locking operations can be nested, but each page-locking must be balanced by 
a corresponding unlocking. 


See Also GlobalPageLock 


GlobalReAlloc 


HGLOBAL GlobalReAlloc(hg/b, chNewSize, fuAlloc) 
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[ 2x] 


HGLOBAL /eglb; /* handle of memory object to reallocate si 

DWORD cbNewSize; /* new size of object | wl 

UINT fuAlloc; /* how object is reallocated | : i 
The GlobalReAlloc function changes the size or attributes of the given global 
memory object. 

Parameters hglb 


Identifies the global memory object to be reallocated. 


cbNewSize 


Specifies the new size of the memory object. 


fuAlloc 


Specifies how to reallocate the global object. If this parameter includes 


GMEM_ MODIFY, the GlobalReAlloc function ignores the cbNewSize 


parameter. 
Value 
GMEM_DISCARDABLE 


GMEM_MODIFY 


GMEM_MOVEABLE 


GMEM_NODISCARD — 


Meaning 


Causes a previously movable object to become 
discardable. This flag can be used only with 
GMEM_MODIFY. | 


Modifies the object’s memory flags. This flag can 
be used with GMEM_DISCARDABLE and 
GMEM_MOVEABLE. 


Causes a previously movable and discardable object 
to be discarded, if the cbNewSize parameter is zero 
and the object’s lock count is zero. If chNewSize is 
zero and the object is not movable and discardable, 
this flag causes the GlobalReAlloc function to fail. 


If chNewSize is nonzero and the object identified by 
the hglb parameter is fixed, this flag allows the reallo- 


' cated object to be moved to a new fixed location. 


If a movable object is locked, this flag allows the ob- 


. ject to be moved to a new locked location without in- 


validating the handle. This may occur even if the 
object is currently locked by a previous call to the 
GlobalLock function. 


‘If this flag is used with GMEM_ MODIFY, the.” 


GlobalReAlloc function changes a fixed memory | 
object to a movable memory object. 

Prevents memory from being discarded to satisfy the 
allocation request. This flag cannot be used with. 


GMEM_MODIFY. 
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Return Value 


Comments 


Value ; Meaning 


GMEM_ZEROINIT Causes the additional memory to be initialized to 
zero if the object is growing. This flag cannot be 
used with GMEM_MODIFY. 


The return value is the handle of the reallocated global memory if the function is 
successful. It is NULL if the object cannot be reallocated as specified. 


If GlobalReAlloc reallocates a movable object, the return value is a handle to the 
memory. To access the memory, an application must use the GlobalLock function 
to convert the handle to a pointer. 


To free a global memory object, an application should use the GlobalFree func- 
tion. 


The GMEM_ZEROINIT flag will cause applications to fail if it is used as shown 
in the following sequence: 


hMem 


GlobalAlloc(GMEM_ZEROINIT | (other flags), dwSizel); 


hMem = GlobalReAlloc(hMem, dwSize2, GMEM_ZEROINIT | (other flags)); 


/* where dwSize2 > dwSizel. */ 


hMem = GlobalReAlloc(hMem, dwSize3, GMEM_ZEROINIT | (other flags)); 


/* where dwSize3 < dwSize2. */ 


hMem = GlobalReAlloc(hMem, dwSize4, GMEM_ZEROINIT | (other flags)); 


/* QMEM_ZEROINIT fails when dwSize4 > dwSize3. */ 


In the last step of the preceding example, the memory between dwSize3 and the in- 
ternal allocation boundary is not set to zero. After the last step, the contents of the 
buffer equal its contents prior to the call to GlobalReAlloc that specified dwSize3. 


Gi0ovalAloc, GiovalDistar a, Giovalrr ce, Gi0dpalLOCK | 
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GlobalSize . [2x] 


DWORD GlobalSize(hglb) | 
HGLOBAL hglb; /* handle of memory object to return size of J ae 


The GlobalSize function retrieves the current size, in bytes, of the given global 
memory object. 


Parameters — helb 
Identifies the global memory object. 


Return Value The return value specifies the size, in bytes, of the memory object. It is zero if the | 
specified handle is not valid or if the object has been discarded. 


Comments The size of a memory object is sometimes larger than the size requested at the 
time the memory was allocated. 


An application should call the GlobalFlags function prior to calling the Global- 


Size function, to verify that the specified memory object was not discarded. If the — 
memory object has been discarded, the return value for GlobalSize is meaningless. 


See Also GlobalAlloc, GlobalFlags 


GlobalUnfix © 9 ae [a0 
void GlobalUnfix(hglb) . 
HGLOBAL /hgilb; /* handle of global memory tounlock */ 


The GlobalUnfix function cancels the effects of the GlobalFix function and al- 
lows a global memory object to be moved in linear memory. — 


Parameters -—S=agilb 
_ Identifies the global memory object to be unlocked. 


~ Return Value — | | This function does not return a value. — 
Comments 3 This function interferes with effective Windows memory management and can re- 
_ sult in linear-address fragmentation. — applications need to fix memory in linear 


address space. 


Each time an application calls the GlobalFix function for an object, it must eventu- 
ally call the GlobalUnfix function for the object. 
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GlobalUnfix decrements (decreases by one) the object’s lock count and returns 
the new lock count in the CX register. The object is completely unlocked and sub- 
ject to moving or discarding if the lock count is decremented to zero. Other func- 
tions also can affect the lock count of a memory object. For a list of these 
functions, see the description of the GlobalFlags function. 


See Also GlobalFix, GlobalFlags 


GlobalUnlock [2x | 


BOOL GlobalUnlock(hglb) 
HGLOBAL heglb; /* handle of global memory to unlock *] 


The GlobalUnlock function unlocks the given global memory object. This func- 
tion has no effect on fixed memory. 


Parameters hglb 
Identifies the global memory object to be unlocked. 


Return Value The return value is zero if the object’s lock count was decremented (decreased by 
| one) to zero. Otherwise, the return value is nonzero. 


Comments With movable or discardable memory, this function decrements the object’s lock 
count. The object is completely unlocked and subject to moving or discarding if 
the lock count 1s decreased to zero. 


This function returns nonzero if the given memory object is not movable. An appli- 
cation should not rely on the return value to determine the number of times it must 
subsequently call the GlobalUnlock function for the memory object. 


Other functions can also affect the lock count of a memory object. For a list of the 
functions that affect the lock count, see the description of the GlobalFlags func- 
tion. 


Each time an application calls GlobalLock for an object, it must veuueny call 
the GlobalUnlock function for the object. 


See Also GlobalFlags, GlobalLock, UnlockResource 


GlobalUnWire 


BOOL GlobalUnWire(hgib) 
HGLOBAL hegib; 


This function should not be used in Windows 3.1. 


See Also GlobalUnlock 


GlobalWire 


void FAR* GlobalWire(hglb) 
HGLOBAL hgib; 


See Also GlobalLock — 


GrayString 


BOOL GrayString(hdc, oe gsprc, lParam, cch, x, y, CX, Cy) 


HDC hdc; /* handle of device context 
HBRUSH hbr; /* handle of brush for graying 
GRAYSTRINGPROC gsprc; /* address of callback function 
LPARAM lParam; /* address of application-defined data 
int cch; | _ /* number of characters to output 
intx; | /* horizontal position 
int y;__ /* vertical position 

int cx; : /* width 
int cy; : /* height 


This function should not be used in Windows 3.1. 


GrayString 


021 


[ 2.x | 


The GrayString function draws gray (dim) text at the given location by writing 

the text in a memory bitmap, graying the bitmap, and then copying the bitmap to 
the display. The function grays the text regardless of the selected brush and back- . 

ground. GrayString uses the font currently selected for the given device context. _ 


Parameters §= = hdc 
Identifies the device context. 
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Return Value 


Comments 


hbr 
Identifies the brush to be used for graying. 


gspre 
Specifies the procedure-instance address of the application-supplied callback 
function that will draw the string. The address must be created by the Make- 
ProcInstance function. For more information about the callback function, see 
the description of the GrayStringProc callback function. 


If this parameter is NULL, the system uses the TextOut function to draw the 
string, and the /Param parameter is assumed to be a long pointer to the charac- 
ter string to be output. 


lParam 
Points to data to be passed to the output function. If the gsprc parameter is 
NULL, the /Param parameter must point to the string to be output. 


cch 
Specifies the number of characters to be output. If this parameter is zero, the 
GrayString function calculates the length of the string (assuming that the 
/Param parameter is a pointer to the string). If cch is —1 and the function 
pointed to by the gsprc parameter returns zero, the image is shown but not 
grayed. 


Specifies the logical x-coordinate of the starting position of the rectangle that 
encloses the string. 


Specifies the logical y-coordinate of the starting position of the rectangle that — 
encloses the string. 


Cx 
Specifies the width, in logical units, of the rectangle that encloses the string. If 
this parameter is zero, the GrayString function calculates the width of the area, 
assuming the /Param parameter is a pointer to the string. 


cy | 
Specifies the height, in logical units, of the rectangle that encloses the string. If 
this parameter is zero, the GrayString function calculates the height of the 
area, assuming the /Param parameter 1s a pointer to the string. 


The return value is nonzero if the function is successful. It is zero if either the 
TextOut function or the application-supplied output function returns zero, or if 


_ there is insufficient memory to create a memory bitmap for graying. 


An application must select the MM_TEXT mapping mode before using this func- 
tion. 
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If TextOut cannot handle the string to be output (for example, if the string is _ 
stored as a bitmap), the gsprc parameter must point to a callback function that will 
draw the string. 


An application can draw grayed strings on devices that support a solid gray color 
without calling the GrayString function. The system color COLOR_GRAYTEXT 
is the solid-gray system color used to draw disabled text. The application can call 
the GetSysColor function to retrieve the color value of COLOR_GRAYTEXT. If 
the color is other than zero (black), the application can call the SetTextColor func- 
tion to set the text color to the color value and then draw the string directly. If the 
retrieved color is black, the application must call GrayString to gray the text. 


See Also ~ GetSysColor, MakeProcInstance, SetTextColor, TextOut 


GrayStringProc | * 


BOOL CALLBACK GrayStringProc(hdc, [pData, cch) 


HDC hdc; /* handle of device context */ 
LPARAM IpData; /* address of string to be drawn a | 
int cch; /* length of string to be drawn *} 


The GrayStringProc function is an application-defined callback function that 
draws a string as a result of a call to the GrayString function. 


~ Parameters hdc | : 
Identifies a device context with a bitmap of at least the width and height 
specified by the cx and cy parameters passed to the GrayString function. 
lpData 
Points to the string to be drawn. 


cch 
Specifies the length, in characters, of the string. 


Return Value The daliback function should return TRUE to indicate success. Otherwise it should 
return ee 
Comments The callback function must draw an image relative to the coordinates (0,0). | 


GrayStringProc is a placeholder for the application- -defined function name. The 
actual name must be exported by including it in an EXPORTS statement in the ap- 
plication’s module-definition (.DEF) file. 


See Also | GrayString | 
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HardwareProc EXE 


LRESULT CALLBACK HardwareProc(code, wParam, lParam) 


int code; _ /* hook code | */ 
WPARAM wParam; _ /* undefined | a4 
LPARAM /Param; /* address of structure with event information */ 


The HardwareProc function is an application-defined callback function that the 
system calls whenever the application calls the GetMessage or PeekMessage 
function and there is a hardware event to process. Mouse events and keyboard 
events are not processed by this hook. 


Parameters code 
Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If this value is less than zero, the callback function 
should pass the message to CallNextHookEx without further processing. If this 
value is HC_NOREMOVE, the application is using the PeekMessage function 
with the PM_NOREMOVE option, and the message will not be removed from 
the system queue. 


wParam 
Specifies a NULL value. 


lParam 
Points to a HARDWAREHOOKSTRUCT structure. The HARDWARE- 
HOOKSTRUCT structure has the following form: 


typedef struct tagHARDWAREHOOKSTRUCT { /* hhs */ 
HWND hWnd; 
UINT wMessage; 
WPARAM wParam; 
LPARAM 1Param; 
} HARDWAREHOOKSTRUCT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The callback function should return zero to allow the system to process the mes- 
‘ sage; it should be 1 if the message is to be discarded. 


Comments | This callback function should not install a playback hook because the function can- 
| not use the GetMessageExtraInfo function to get the extra information associated 
with the message. 


The callback function must use the Pascal calling convention and must be declared 
FAR. An application must install the callback function by specifying the 
WH_HARDWARE filter type and the procedure-instance address of the ane. 
function in a call to the SetWindowsHookEx function. 


See Also 


hardware_ event 525 


HardwareProc is a placeholder for the library-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the library’s 
module-definition (.DEF) file. — 


CallNextHookEx, GetMessageExtraInfo, Set WindowsHookEx 


hardware_event — [3.1 | 


Parameters 


Return Value 


Comments 


extrn hardware_event :far 


mov ax, Msg 

mov cx, ParamL 

mov dx, ParamH 

mov si, hwnd 

mov di, wParam 
cCall hardware_event 


message | 

low-order word of 1]Param of the message 
high-order word of |]Param of the message | 
handle of the destination window 

wParam of the message | 


we we woe we we 


The hardware_ event function places a hardware-related message into the system 
message queue. This function allows a driver for a non-standard hardware device 
to place a message into the queue. 


Msg | 
Specifies the message to place in the system message queue. 
ParamL | | | | 
Specifies the low-order word of the [Param parameter of the message. 


[ParamH : 
Specifies the high-order word of the /Param parameter of the message. 


hwnd 
Identifies the window to which the message is directed. This parameter also be- 
comes the low-order word of the dwExtralnfo parameter associated with the 
message. An application can determine the value of this parameter by calling 
the GetMessageExtraInfo function. 


wParam 
Specifies the wParam parameter of the message. 


a . ee ig, ee 
The return value is nonzero if the function is successful. Otherwise, it 1s zero. 


An application should not use this function to place keyboard or mouse messages 
into the system message queue. | 
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An application may only call the hardware_event function from an assembly lan- 
guage routine. The application must declare the function as follows: 


extrn hardware_event :far 


‘Tf the application includes CMACROS.INC, the application can declare the func- | 
tion as follows: 


extrnFP hardware_event. 


See Also GetMessageExtralInfo 


HideCaret [2x | 


void HideCaret(hwnd) 
HWND hwnd; /* handle of window with caret +f 


The HideCaret function hides the caret by removing it from the screen. Although 
the caret is no longer visible, it can be displayed again by using the ShowCaret 
function. Hiding the caret does not destroy its current shape. 


Parameters hwnd 


Identifies the window that owns the caret. This parameter can be set to NULL 
to specify indirectly the window in the current task that owns the caret. 


Return Value This function does not return a value. 


Comments The HideCaret function hides the caret only if the given window owns the caret. 
If the hwnd parameter is NULL, the function hides the caret only if a window in 
the current task owns the caret. | 


Hiding is cumulative. If HideCaret has been called five times in a row, Show- 
Caret must be called five times before the caret will be shown. 


See Also CreateCaret, ShowCaret 


HiliteMenultem 
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[ 2.x | 


BOOL HiliteMenultem(hwnd, hmenu, idHiliteltem, fuHilite) 


HWND hwnd; /* handle of window with menu ed 
HMENU hmenu; /* handle of menu ‘ald 
UINT idHiliteltem; /* menu-item identifier ‘at 
UINT fuHilite; /* highlight flags a 
The HiliteMenultem function highlights or removes the highlighting from a top- 
level (menu-bar) menu item. 
Parameters hwnd 
Identifies the window that contains the menu. 
hmenu 
Identifies the top-level menu that contains the item to be highlighted. 
idHiliteltem 
Specifies the menu item to be highlighted, as determined by the fuHilite param- 
eter. 
fuHilite 


Specifies whether the menu item is highlighted or the highlight is removed. It 
can be a combination of the MF_HILITE or MF_UNHILITE value with the 
MF _BYCOMMAND or MF_BYPOSITION value. These values have the fol- 


lowing meanings: 
Value 
MF_BYCOMMAND 


MF _BYPOSITION 
ME_HILITE 


MF_UNHILITE 


~ Return Value 


Comments 


| Meaning 


Menu-item identifier is specified by the idHiliteltem pa- 
rameter (the default interpretation). | 


Zero-based position of the menu item is eet by the 
idHilite[tem parameter. 

Menu item is highlighted. If this value is not given, 
highlighting is removed from the menu item. 


Highlighting is removed from the menu item. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The MF_HILITE and MF_UNHILITE flags can be used only with the Hilite- 


Menultem function; they cannot be used with the ModifyMenu function. 


See Also 


CheckMenulItem, EnableMenulItem, ModifyMenu 
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hmemepy «Peal 


void hmemcpy(hpvDest, hpvSource, cbCopy) i = 
void _huge* hpvDest; | /* address of destination buffer a 


const void _ huge* hpvSource; /* address of source buffer i | 
long cbCopy; /* number of bytes to copy **/ 


The hmemecpy function copies bytes from a source buffer to a destination buffer. 
This function supports huge memory objects (that is, objects larger than 64K, allo- 
cated using the GlobalAlloc function). 


Parameters hpvDest | 
Points to a buffer that receives the copied bytes. 


hpvSource 
Points to a buffer that contains the bytes to be copied. 


cbCopy 
Specifies the number of bytes to be copied. 


Return Value This function does not return a value. 


See Also | _hread, _hwrite, Istrepy 


_hread | | EN 


long _hread(hf, hpvBuffer, cbBuffer) 


HFILE hf; /* filehandle */ 
void _huge* hpvBuffer; /* address of buffer for read data sa | 
long cbBuffer; /* length of data buffer */ 


The _hread function reads data from the specified file. This function supports 
huge memory objects (that is, objects larger than 64K, allocated using the 
GlobalAlloc function). 


Parameters hf 
Identifies the file to be read. 
hpvBuffer | 
Points to a buffer that is to receive the data read from the file. 


cbBuffer | | 
Specifies the number of bytes to be read from the file. 


Return Value 


See Also 


_hwrite 
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The return value indicates the number of bytes that the function read from the file, 
if the function is successful. If the number of bytes read is less than the number 
specified in cbBuffer, the function reached the end of the file (EOF) before reading 
the specified number of bytes. The return value is —1L if the function fails. 


_lread, hmemcpy, _ hwrite 


long _hwrite(Af, hpvBuffer, cbBuffer) 


Return Value 


Comments 


See Also 


— HFILE hf; /* file handle my 
- const void _huge* hpvBuffer; /* address of buffer for write data */ 
long cbBuffer; /* size of data */ 
The _ hwrite function writes data to the specified file. This function supports huge 
memory objects (that is, objects larger than 64K, allocated using the GlobalAlloc 
function). 
Parameters hf 
Identifies the file to be written to. 
hpvBuffer 
Points to a buffer that contains the data to be written to the file. 
cbBuffer 


Specifies the number of bytes to be written to the file. 


The return value indicates the number of bytes written to the file, if the function is 
successful. Otherwise, the return value is —1L. | 


MS-DOS error values are not available when an application calls this function. 


hmemcpy, _hread, _Iwrite 
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InflateRect 


void InflateRect(/prc, xAmt, yAmt) 


RECT FAR®* Iprc; 


int xAmt; 
int yAmt; 


Parameters 


Return Value 


Comments 


See Also 


/* address of rectangle i 
/* amount to increase or decrease width id 
/* amount to increase or decrease height _ a 


The InflateRect function increases or decreases the width and height of a 
rectangle. The InflateRect function adds xAmt units to the left and right ends of 
the rectangle and adds yAmt units to the top and bottom. The xAmt and yAmt pa- 
rameters are signed values; positive values increase the width and height, and 
negative values decrease them. 


lpre | 
Points to the RECT structure that increases or decreases in size. The RECT 
structure has the following form: 


typedef struct tagRECT { /* rc x*/ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


xAmt 
Specifies the amount to increase or decrease the rectangle width. It must be 
negative to decrease the width. 


yAmt : 

Specifies the amount to increase or decrease the rectangle height. It must be 
negative to decrease the height. 

This function does not return a value. 


The width and height of a rectangle must not be greater than 32,767 units or less 
than —32,768 units. 


IntersectRect, OffsetRect, UnionRect 
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InitAtomTable aera 


BOOL InitAtomTable(cTableEntries) 


int cTableEntries; 


Parameters 


Return Value 


Comments 


Example 


/* size of atom table */ 


The InitAtomTable function initializes the local atom hash table and sets it to the 
specified size. 


An application need not use this function to use a local atom table. The default 
size of the local and global atom hash tables is 37 table entries. If an application 
uses InitAtomTable, however, it should call the function before any other atom- 
management function. 


clableEntries 


Specifies the size, in table entries, of the atom hash table. This value should be 
a prime number. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


If an application uses a large number of local atoms, it can increase the size of the 
local atom table, reducing the time required to add an atom to the local atom table 
or to find an atom in the table. However, this increases the amount of memory re- 
quired to maintain the table. — 


The size of the global atom table cannot be changed from its default size of 37 en- 
tries. 


The following example uses the InitAtomTable function to change the size of the 
local atom table to 73: 


BOOL fSuccess; 
fSuccess = InitAtomTable(73); 


if (fSuccess) : 
| MessageBox(hwnd, “table initialization succeeded", 
"InitAtomTable", MB_OK); 
else : 
MessageBox(hwnd, “table initialization failed", 
"InitAtomTable", MB_ICONEXCLAMATION) ; 
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InSendMessage [2x | 


BOOL InSendMessage(void) 


The InSendMessage function specifies whether the current window procedure 
is processing a message that was sent from another task by a call to the Send- 


Message function. 

Parameters This function has no parameters. 

Return Value =—‘ The return value is nonzero if the window procedure is processing a message sent 
to it from another task by the SendMessage function. Otherwise, the return value 
iS Zero. 

Comments Applications use the InSendMessage function to determine how to handle errors 


that occur when an inactive window processes messages. For example, if the ac- 
tive window uses the SendMessage function to send a request for information to 
another window, the other window cannot become active until it returns control 
from the SendMessage call. The only method an inactive window has to inform 
the user of an error is to create a message box. 


See Also _ PostAppMessage, SendMessage 


InsertMenu 


BOOL InsertMenu(hmenu, idltem, fuF lags, idNewlItem, lpNewlItem) 


HMENU hmenu; /* handle of menu */ 
UINT idltem; /* menu item that new menu item is to precede */ 
UINT fuFlags; /* menu flags a 
UINT idNewltem; /* item identifier or pop-up menu handle **/ 
LPCSTR /pNewltem; /* item content | */ 


The InsertMenu function inserts a new menu item into a menu, moving other 
items down the menu. The function also sets the state of the menu item. 


GMa ewe wrowrevy ? 


Identifies the menu to be changed. 


idItem | | 
Specifies the menu item before which the new menu item is to be inserted, as 
determined by the fuFlags parameter. , 


Paramatare hmonu 
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fuFlags 3 
Specifies how the id/tem parameter is interpreted and information about the 
state of the new menu item when it is added to the menu. This parameter con- 
sists of a combination of one of the following values and the values listed in the 
Comments section. 


Value _ | Meaning 
MF_BYCOMMAND The idltem parameter specifies the menu-item identifier. 
MF_BYPOSITION | The idltem parameter specifies the zero-based position of 


the menu item. If idltem is —1, the new menu item is ap- 
pended to the end of the menu. 


idNewltem 
Specifies either the identifier of the new menu item or, if fuF’ lags i is set to 
MF_POPUP, the menu handle of the pop-up menu. 


ea kailedit 
Specifies the contents of the new menu item. If fuFlags is set to MF_STRING 
(the default value), this parameter points to a null-terminated string. If fuFlags 
is set to MF_BITMAP instead, [pNewlItem contains a bitmap handle in its low- 
order word. If fuFlags is set to MF_OWNERDRAW, [pNewltem specifies an 
application-defined 32-bit value, which the application can use to maintain addi- 
tional data associated with the menu item. This 32-bit value is available to the 
application in the itemData member of the structure pointed to by the [Param 
parameter of the WM_MEASUREITEM and WM_DRAWITEM messages. 
These messages are sent when the menu item is initially displayed or is 


changed. 
: Return Value The return value is nonzero Dat the function is successful. Otherwise, it is zero. 
Comments If the active multiple document interface (MDI) child window 1s maximized and 


an application inserts a pop-up menu into the MDI application’s menu by calling | 
this function and specifying the MF_BYPOSITION flag, the menu is inserted one 
position farther left than expected. This occurs because the System menu of the ac- 
tive MDI child window is inserted into the first position of the MDI frame win- 
dow’s menu bar. To avoid this behavior, the application must add 1 to the 
position value that would otherwise be used. An application can use the 

~ WM_MDIGETACTIVE message to determine whether the currently active 

— child window i is maximized. - 


ss 2 Whenever a menu changes (whether or not the menu is in a window that is dis- 
played), the application should call the DrawMenuBar function. 


: Each of the following groups lists dies that should not be used oars 


3 7. ~MF-_ _BYCOMMAND and MF _BYPOSITION : 
a MF DISABLED, MF ENABLED, and MF _ GRAYED 
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=» MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR 


= MF_MENUBARBREAK and MF_MENUBREAK 
~™ MF CHECKED and MF_UNCHECKED 


The following list describes the flags that may be set in the fuF lags parameter: 


Value 
MF_BITMAP 


MF_BYCOMMAND 
MF_BYPOSITION 


MF_CHECKED 


MF_DISABLED 
MF_ENABLED 
MF_GRAYED 


MF_MENUBARBREAK 


MF_MENUBREAK 


-MF_OWNERDRAW 


MF_POPUP 


Meaning 


Uses a bitmap as the item. The low-order word of the 
IpNewltem parameter contains the handle of the bitmap. 
Specifies that the id/tem parameter gives the menu-item 
identifier (default). | 
Specifies that the id/tem parameter gives the position of 
the menu item rather than the menu-item identifier. 
Places a check mark next to (selects) the menu item. If 
the application has supplied check-mark bitmaps (see the 
SetMenultemBitmaps function), setting this flag dis- 


_ plays the check-mark bitmap next to the menu item. 


Disables the menu item so that it cannot be selected, but 
does not gray (dim) it. 


Enables the menu item so that it can be selected, and re- 


stores it from its grayed state. 


Disables the menu item so that it cannot be selected, and 
grays it. 

Same as MF_MENUBREAK except, for pop-up menus, 
separates the new column from the old column by using 
a vertical line. 


Places the menu item on a new line for static menu-bar 
items. For pop-up menus, places the menu item in a new 
column, with no dividing line between the columns. 


Specifies that the item is an owner-drawn item. 

The window that owns the menu receives a 
WM_MEASUREITEM message (when the menu is dis- 
played for the first time) to retrieve the height and width 
of the menu item. The WM_DRAWITEM message is 
then sent to the owner whenever the owner must update 
the visual appearance of the menu item. This option is 
not valid for a top-level menu item. 


Specifies that the menu item has a pop-up menu as- 
sociated with it. The idNewltem parameter specifies a 
handle of a pop-up menu to be associated with the item. 
Use the MF_OWNERDRAW flag to add either a top- 
level pop-up menu or a hierarchical pop-up menu to a 


_ pop-up menu item. 
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Value _ - Meaning 


MF_SEPARATOR Draws a horizontal dividing line. You can use this flag 
in a pop-up menu. This line cannot be grayed, disabled, 
or highlighted. Windows ignores the IpNewltem and 
idNewltem parameters. 


| MF_STRING Specifies that the menu item is a | character string; the 
IpNewlItem parameter points to the string for the item. 
MF_ UNCHECKED Does not place a check mark next to the item (default 


value). If the application has supplied check-mark bit- 
maps (see SetMenultemBitmaps), setting this flag dis- 
plays the check-mark-off bitmap next to the menu item. 


See Also AppendMenu, CreateMenu, DrawMenuBar, RemoveMenu, 
: SetMenultemBitmaps 


InterruptRegister eae oe [ 3.1 | 


~ include <toolhelp.h> 
BOOL InterruptRegister(itask, IpfnIntCallback) 


_ HTASK hiask; /* handle of task oy 


-FARPROC [pfnintCallback; /* address of callback function **/ 


The InterruptRegister function installs a callback function to handle all system 
interrupts. | 


Parameters htask 
. Identifies the task that is registering the callback function. The htask value is 
for registration purposes, not for filtering interrupts. Typically, this value is 
NULL, indicating the current task. The only time this value is not NULL is" 
when an application requires more than one interrupt handler. 


[pfnIntCallback 
Points to the interrupt callback function that will handle interrupts. The Tool 
Helper library calls this function whenever a task receives an interrupt. 


The [pfnIntCallback value is normally the return value of a call to the Make- 
ProcInstance function. This causes the interrupt callback function to be 
entered with the AX register set to the selector of the application’s data seg- 
ment. Usually, an exported function prolog contains the following code: 


mov ds,ax 


Return Value __ The return value is nonzero if the function is successful. Otherwise, it is zero. | 
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Comments 


The syntax of the function pointed to by [pfnIntCallback is as follows: 
void InterruptRegisterCallback(void) 


InterruptRegisterCallback is a placeholder for the application-defined function 
name. The actual name must be exported by including it an EXPORTS in the ap- 
plication’s module-definition file. 


An interrupt callback function must be reentrant, must be page-locked, and must 
explicitly preserve all register values. When the Tool Helper library calls the func- 
tion, the stack will be organized as shown in the following illustration. | 


CS (fault) 
) 
| 


SP + 12h 
SP + 10h 


SP + OEh 


SP + 0Ch 


(fault 
IP (fault 


SP + OAh 


SP + 08h 


Handle (internal) 

Interrupt number 
<i 

p 


SP + 06h 


SP + 04h 


SP + 02h 


CS (TOOLHELPDLL) 
IP (TOOLHELP.DLL) 


The SS and SP values will not be on the stack unless a low-stack fault occurred. 


SP + 00h 


This fault is indicated by the high bit of the interrupt number being set. 


When Windows calls a callback function, the AX register contains the DS value 
for the instance of the application that contains the callback function. For more in- 
formation about this process, see the MakeProclInstance function. | 


Typically, an interrupt callback function is exported. If it is not exported, the 
developer should verify that the appropriate stack frame is generated, including the 
correct DS value. 
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An interrupt callback function must save and restore all register values. The func- 
tion must also do one of the following: 


= Execute an retf instruction if it does not handle the interrupt. The Tool Helper 
library will pass the interrupt to the next appropriate handler1 in the interrupt 
handler list. 


= Terminate the application by using the TerminateApp function. 


= Correct the problem that caused the interrupt, clear the first 10 bytes of the 
- stack, and execute an iret instruction. This action will restart execution at the 
specified address. An application may change this address, if necessary. 


= Execute a nonlocal goto to a known position in the application by using the 
Catch and Throw functions. This type of interrupt handling can be hazardous; 
the system may be in an unstable state and another fault may occur. Applica- 
tions that handle interrupts in this way must verify that the Fault was a result of 
the appcation: s code. 


The Tool Helper library supports the following interrupts: 


Name Number Meaning 

INT_DIVO 0 Divide-error exception 

INT_1 1 Debugger interrupt 

INT_3 oak ae Breakpoint interrupt 

INT_UDINSTR fe 36 Invalid-opcode exception 

INT_STKFAULT | 12 Stack exception 

INT_GPFAULT 13 General protection violation 

INT_ BADPAGEFAULT 14. Page fault not caused by normal virtual- 
| memory operation _ | 

INT_CTLALTSYS RQ 256 User pressed CTRL+ALT+SYS RQ 


The Tool Helper library returns interrupt numbers as word values. Normal soft- 
ware interrupts and processor faults are represented by numbers in the range 0 
through 255. Interrupts specific to Tool pee are cree oie by numbers eee | 
than 255. 


Some developers may wish to use CTRL+ALT+SYS RQ nterrupt 256) to break into 
the debugger. Be cautious about implementing this interrupt, because the point at 
which execution stops will probably be in a sensitive part of the Windows kernel. 
All InterruptRegisterCallback functions must be page-locked to prevent prob- 
lems when this interrupt is used. In addition, the debugger probably will not be. 
able to perform user-interface functions. However, the debugger can use Tool 
~ Helper functions to set breakpoints and gather information. The debugger _ 

may also be able to use a debugging terminal or secondary screen to display 
information. | 
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See Also 


InterruptUnRegister 


Low-stack Faults | 

A low-stack fault occurs when inadequate stack space is available on the faulting 
application’s stack. For example, if any fault occurs when there is less than 128 
bytes of stack space available or if runaway recursion depletes the stack, a low- 
stack fault occurs. The Tool Helper library picresees a low-stack fault differently 
than it processes other faults. 


A low-stack fault is indicated by the high-order bit of the interrupt number being 
set. For example, if a stack fault occurs and the SP value becomes invalid, the 
Tool Helper library will return the fault number as Ox800C rather than OxO00C. 


Interrupt handlers designed to process low-stack faults must be aware that the 

Tool Helper library has passed a fault frame on a stack other that the faulting appli- 
cation’s stack. The SS:SP value is on the stack because it was pushed before the 
rest of the information in the stack frame. The SS:SP value is available only for ad- 
visory purposes. 


An interrupt handler should never restart the faulting instruction, because this 
will cause the system to crash. The handler may terminate the application with 
TerminateApp or pass the fault to the next handler in the interrupt-handler list. 


Interrupt handlers should not assume that all stack faults are low-stack faults. For 
example, if an application accesses a stack-relative variable that is out of range, a 
stack fault will occur. This type of fault can be processed in the same manner as 
any general protection (GP) fault. If the high-order bit of the interrupt number is 
not set, the instruction can be restarted. 


Interrupt handlers also should not assume that all low-stack faults are stack faults. 
Any fault that occurs when there is less than 128 bytes of stack available will 
cause a low-stack fault. 


Interrupt callback functions that are not designed to process low-stack faults 
should execute an retf instruction so that the Tool Helper library will pass the fault 
to the next appropriate handler in the interrupt-handler list. 


Catch, InterruptUnRegister, NotifyRegister, NotifyUnRegister, 
TerminateApp, Throw 


#include <toolhelp.h> 
BOOL InterruptUnRegister(htask) 


HTASK htask; 


/* handle of task —-*/ 


Parameters 


Return Value 


Comments 


See Also 


IntersectClipRect 
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The InterruptUnRegister function restores the default pag handle for sys- 
tem interrupts. 


htask 


Identifies the task. If this value is NULL, it identifies the current task. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


After this function is executed, the Tool Helper library will pass all interrupts it re- 
ceives to the system’s default interrupt handler. 


InterruptRegister, NotifyRegister, NotifyUnRegister, TerminateApp 


int IntersectClipRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect) 


HDC hdc; 

int nLeftRect; 

int nTopRect; 

int nRightRect; 
int nBottomRect; 


Parameters 


~ Return Value — 


/* handle of device context i 
/* x-coordinate top-left corner of rectangle | =} 
/* y-coordinate top-left corner of rectangle a 
/* x-coordinate bottom-right corner of rectangle sf 
/* y-coordinate bottom-right corner of rectangle i] 


The IntersectClipRect function creates a new clipping region from the intersec- 
tion of the current region and a specified rectangle. 


hdc 
Identifies the device context. 


nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the ecundie 


nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the pcialele 


nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


The return value specifies that the resulting region has overlapping borders 
(COMPLEXREGION), is empty (NULLREGION), or has no overlapping borders 


(SIMPLEREGION). Otherwise, the return value is ERROR. 
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Comments An application uses the IntersectClipRect function to create a clipping region 
from the intersection of the current region and a specified rectangle. An applica- 
tion can also create a clipping region that is the intersection of two regions, by 
specifying RGN_AND in a call to the CombineRgn function and then making 
this combined region the clipping region by calling the SelectClipRgn function. 


The width of the rectangle, specified by the absolute value of nRightRect — 
nLeftRect, must not exceed 32,767 units. This limit applies to the height of the 
rectangle as well. | 


Example The following example creates a square clipping region and colors it red by using 
a red brush to fill the client area. The IntersectClipRect function is called with 
coordinates that overlap the region, and the client area is filled with a yellow 
brush. The only region colored yellow is the overlap between the region and the 
coordinates specified in the call to IntersectClipRect. 


RECT rc; 
HRGN hrgn; 
HBRUSH hbrRed, hbrYellow; 


GetClientRect(hwnd, &rc); 

hrgn = CreateRectRgn(10, 10, 110, 110); 
SelectClipRgn(hdc, hrgn); 

hbrRed = CreateSolidBrush(RGB(255, 0, @)); 
FillRect(hdc, &rc, hbrRed); 


IntersectClipRect(hdc, 100, 100, 200, 200); 


hbrYellow = CreateSolidBrush(RGB(255, 255, @)); 
FillRect(hdc, &rc, hbrYellow); 


DeleteObject(hbrRed); 
DeleteObject(hbrYel low); 
DeleteObject(hrgn) ; 


See Also | CombineRgn, SelectClipRgn 


IntersectRect : — [2x | 


BOOL IntersectRect(/prcDst, lprcSrc1, IprcSrc2) : 
RECT FAR?® [prcDst; /* address of structure for intersection **/ 
const RECT FAR® IprcSrc1; /* address of structure with Ist rectangle | 
const RECT FAR* [prcSrc2;__—_—s/* address of structure with 2nd rectangle ae 


Parameters 


Return Value 


See Also 


InvalidateRect 


InvalidateRect 


The IntersectRect function calculates the intersection of two source rectangles 
and places the coordinates of the intersection rectangle into the destination 
rectangle. If the rectangles do not intersect, an empty rectangle (0, 0, 0, 0) is 
placed into the destination rectangle. 


lprcDst 
Points to a RECT structure that receives the intersection of the rectangles 
pointed to by the lprcSrc1 and lprcSrc2 parameters. The RECT structure has 
the following form: 


typedef struct tagRECT { /* ro x*/ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. pa a 


lpreSrel | | 
Points to the RECT structure that contains the first source rectangle. 


IprcSrc2 - 
Points to the RECT structure that contains the second source rectangle. 


The return value is nonzero if the rectangles intersect. Otherwise, it is zero. 


InflateRect, SubtractRect, UnionRect 


void InvalidateRect(hwnd, lprc, fErase) 


041 


HWND hwnd; /* handle of window with changed update region / 

const RECT FAR® [prc; /* address of structure with rectangle */ 

BOOL /Erase; /* erase-background flag mI, 

| The InvalidateRect function adds a rectangle to a window’s update region. The 
update region represents the client area of the window that must be redrawn. 

Parameters hwnd 


Identifies the window whose update region has changed. 
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— Ipre 


Return Value 


Comments 


See Also 


InvalidateRan 


Points to a RECT structure that contains the client coordinates of the rectangle 
to be added to the update region. If the prc parameter is NULL, the entire 
client area is added to the update region. 


The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


fErase 


Specifies whether the background within the update region is to be erased when 
the update region is processed. It this parameter is TRUE, the background i 1S 
erased when the BeginPaint function is called. If this parameter is FALSE, the 
background remains unenanece 


This function does not return a value. 


The invalidated areas accumulate in the update region until the region is processed 
when the next WM_PAINT message occurs, or until the region is validated by 
using the ValidateRect or ValidateRgn function. 


Windows sends a WM_PAINT message to a window whenever its update region 
is not empty and there are no other messages in the application queue for that win- 
dow. 


If the fErase parameter is TRUE for any part of dis agate region, the Pape sama 
is erased in the entire region, not just in the given part. | 


BeginPaint, InvalidateRgn, ValidateRect, ValidateRgn 


void InvalidateRgn(hwnd, hrgn, fErase) 

HWND hwnd; __—/* handile of window with changed update region he | 
HRGN hrgn; /* handle of region to add i 
BOOL fErase; —_—‘/* erase-background flag */ 
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The InvalidateRgn function adds a region to a window’s update region. The up- 
date region represents the client area of the window that must be redrawn. 


Parameters hwnd 
Identifies the window whose update region has changed. 
hren | : | 
Identifies the region to be added to the update region. The region is assumed to 
have client coordinates. If this parameter is NULL, the entire > chient area 1S 
added to the update region. 


fErase 


Specifies whether the background within the update region is to be erased when 
the update region is processed. If this parameter is TRUE, the background 1S 
erased when the BeginPaint function is called. If the parameter is FALSE, the 
background remains unchanged. | 


Return Value This function does not return a value. 


Comments _ _ The invalidated regions accumulate in the update region until the region 1S 
processed when the next WM_PAINT message occurs, or until the region is vali- 
dated by using the ValidateRect or ValidateRgn function. 


Windows sends a WM _PAINT message to a window whenever its update region | 
is not empty and there are no other messages in the application queue for that win- 
dow. 


If the fErase parameter is TRUE for any part of the update region, the background 
is erased in the entire region, not just in the given part. 


See Also BeginPaint, InvalidateRect, ValidateRect, ValidateRgn 


InvertRect — rex 


void InvertRect(hdc, [prc) 
HDC hdc; /* handle of device context */ 
const RECT FAR* (prc; /* address of structure with rectangle  */ 


The InvertRect function inverts a rectangular area. Inversion i is a logical NOT 
operation and flips the bits of each pixel. 


Parameters jie | 
Identifies the device context. 
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Return Value 


Comments 


See Also 


InvertRgn 


lpre 7 7 | 
Points to a RECT structure that contains the logical coordinates of the 
rectangle to be inverted. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


This function does not return a value. 


On monochrome screens, the InvertRect function makes white pixels black and 
black pixels white. On color screens, the inversion depends on how colors are 
generated for the screen. Calling InvertRect twice, specifying the same rectangle, 
restores the display to its previous colors. 


The InvertRect function compares the values of the top, bottom, left, and right 
members of the specified rectangle. If bottom is less than or equal to top, or if 
right is less than or equal to left, the function does not draw the rectangle. 


FillRect | 


~BOOL InvertRgn(hdc, hrgn) 


HDC hdc; 
HRGN hrgn; 


Parameters 


Return Value 


/* handle of device context **/ 
/* handle of region a 


The InvertRgn function inverts the colors in a given region. 


hdc 
Identifies the device context. — 


hrgn | : | bea 
Identifies the region for which colors are to be inverted. — 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments 


Example 


See Also 


IsBadCodePtr 545 


On monochrome screens, the InvertRgn function makes white pixels black and 
black pixels white. On color screens, the inversion depends on how the colors are 
generated for the screen. 


The following example sets the device coordinates of and creates a rectangular re- 
gion, selects the region into a device context, and then calls the InvertRgn func- 
tion to display the region in inverted colors: 


HRGN hrgn; 

hrgn = CreateRectRgn(10, 10, 110, 110); 
SelectObject(hdc, hrgn); 

InvertRgn(hdc, hrgn); 


DeleteObject(hrgn); 


FillRgn, PaintRgn 


IsBadCodePtr ES 


BOOL IsBadCodePtr(/p/n) 


FARPROC Ipfr; 


Parameters 
Return Value 


See Also 


/* pointer to test 2] 


The IsBadCodePtr function determines whether a pointer to executable code 1 1S 
valid. 


Ipfn 


Points to a function. 


The return value is nonzero if the pointer is bad (that is, if it does not point to ex- 
ecutable code). The return value is zero if the pointer is Zoo 


IsBadHugeReadPtr, cigar IsBadReadPtr, IsBadStringPtr, 
IsBadWritePtr 
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IsBadHugeReadPtr a 


BOOL IsBadHugeReadPtr(/p, cb) 
const void _huge* /p; —_—/* pointer to test */ 
DWORD cb; | /* number of allocated bytes */ 


The IsBadHugeReadPtr function determines whether a huge pointer to readable 
memory is valid. 


Parameters Ip 
Points to the beginning of a block of allocated memory. The data object may 
reside anywhere in memory and may exceed 64K in size. 


cb 
Specifies the number of bytes of memory that were allocated. 


Return Value The return value is nonzero if the pointer is bad (that is, if it does not point to read- 
able memory of the specified size). The return value is zero if the pointer is good. 


| See Also IsBadCodePtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, 
IsBadWritePtr 


IsBadHugeWritePtr [34] 


BOOL IsBadHugeWritePtr(/p, cb) 
void _huge* /p;_ —/* pointer to test */ 
DWORD cb; /* number of allocated bytes nf 


The IsBadHugeWritePtr function determines whether a huge pointer to writable 
memory is valid. 


Parameters Ip | | 
Points to the beginning of a block of allocated memory. The data object may 
reside anywhere in memory and may exceed 64K in size. 


cb 
Specifies the number of bytes of memory that were allocated. 


isBadStringPtr 547 


Return Value — The return value is nonzero if the pointer is bad (that is, if it does not point to - 
writable memory of the specified size). The return value is zero if the pointer is 
good. | | 

See Also IsBadCodePtr, IsBadHugeReadPtr, IsBadReadPtr, IsBadStringPtr, 


IsBadWritePtr 


IsBadReadPtr 3a]. 


BOOL IsBadReadPtr(/p, cb) 


const void FAR* /p; /* pointer to test */ 

UINT cb; /* number of allocated bytes —*/ | 
The IsBadReadPtr function determines whether a pointer to readable memory is. 
valid. | 

Parameters dp 


Points to the beginning of a block of allocated memory. | 


cb | 
Specifies the number of bytes of memory that were allocated. 


Return Value The return value is nonzero if the pointer is bad (that is, if it does not point to read- 
| able memory of the specified size). The return value is zero if the pointer is good. 


SeeAlso -~—«sIsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadStringPtr, 
IsBadWritePtr 


IsBadStringPtr = ous [3.1 | 


- BOOL IsBadStringPtr(Ipsz, cchMax) 
— const void FAR®* /psz; /* pointer to test | 
UINT cchMax; /* maximum size of string i) 


The IsBadStringPtr function determines whether a pointer to a string is valid. | 


Parameters === psz | | | 
| | Points to a null-terminated string. 
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cchMax 
Specifies the maximum size of the string, in bytes. 


Return Value The return value is nonzero if the pointer is bad (that is, if it does not point toa 
string of the specified size). The return value is zero if the pointer is good. © 


See Also IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, 
IsBadWritePtr 


IsBadWritePtr ERE 


BOOL IsBadWritePtr(Ip, cb) 


void FAR® Ip; /* pointer to test sa 
UINT cb; /* number of allocated bytes si 
The IsBadWritePtr function determines whether a pointer to writable memory is 
valid. 
Parameters Ip 
Points to the beginning of a block of allocated memory. 
cb 


Specifies the number of bytes of memory that were allocated. 


Return Value The return value is nonzero if the pointer is bad (that is, if it does not point to wri- 
table memory of the specified size). The return value is zero if the pointer is good. 


See Also IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, 
IsBadStringPtr 


IsCharAlpha 


BIVIVI EY ADOT CAREC’ Curly 


char chTest; —__/* character to test | 


The IsCharAlIpha function determines whether a character is in the set of 
language-defined alphabetic characters. 


Parameters 


Return Value 


Comments | 


Example 


See Also 


IsCharAlphaNumeric 549 


chTest 
Specifies the character to be tested. 


The return value is nonzero if the character is in the set of alphabetic characters. 
Otherwise, it is zero. 


The language driver for the current language (the language the user selected at 
setup or by using Control Panel) determines whether the character is in the set. If 
no language has been set, Windows uses an internal function. 7 


The following example uses the IsCharAlpha function to find the first nonalpha- | 
betic character in a string: 


for (lpszNon = 1lpsz; IsCharAlpha(*1pszZNon) ; 
IpszNon = AnsiNext(1pszNon)); 


IsCharAlphaNumeric 


IsCharAlphaNumeric = ee ee 


BOOL IsCharAlphaNumeric(chTesi) : 


char chTest; 


Parameters 


‘Return Value — 


~ Comments 


Example 


a fae character totest */ 


| The IsCharAlphaNumeric function determines whether a character is in the set 


of language- -defined aipnabeuc or numeric characters. 


chTest | 
_ Specifies the character to be tested. 


The return value is nonzero if the character is in either the set of alphabetic charac- 
ters or the set of numeric characters. Otherwise, it is zero. 


The language driver for the current language (the language the user selected at _ 
setup or by using Control Panel) determines whether the character is in the set. it 
no language driver is selected, Windows uses an internal function. | 


The following example uses the IsCharAlphaNumeric function to find the first 
nonalphanumeric character in a string: 
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for (lpszNon = Ipsz; IsCharAlphaNumeric(*1pszNon) ; 
IpszNon = AnsiNext(1pszNon)); 


See Also IsCharAlpha 


IsCharLower 


BOOL IsCharLower(chTest) 
char chTest; /* character to test */ 


The IsCharLower function determines whether a character is in the set of 
language-defined lowercase characters. 


Parameters chTest 
Specifies the character to be tested. 


Return Value The return value is nonzero if the character is lowercase. Otherwise, it is zero. 


Comments The language driver for the current language (the language selected at setup or by 
using Control Panel) determines whether the character is in the set. If no language 
driver is selected, Windows uses an internal function. 


Example The following example uses the IsCharLower function to find the first lowercase 
character in a string: 


/* Look through string for a lowercase character. */ 
for (lpszLower = 1psz; 
!IsCharLower(*lpszLower) && IpszLower != ‘'\Q@'; 
IpszLower = AnsiNext(1pszLower) ); 


/* Return NULL if no lowercase character is found. */ 


if (IpszLower == '\@') 
TpszLower = NULL; 


See Also IsCharUpper 
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IsCharUpper 


BOOL IsCharUpper(chTest) 
char chTest; /* character to test */ 


The IsCharUpper function determines whether a character is in the set of | 
language-defined uppercase characters. 


Parameters chTest 
Specifies the character to be tested. 


Return Value — The return value is nonzero if the character is uppercase. Otherwise, it 1s zero. 


Comments The language driver for the current language (the language the user selected at 
setup or by using Control Panel) determines whether the character is in the set. If 
no language driver is selected, Windows uses an internal function. 7 


Example The following example uses the IsCharUpper function to find the first uppercase 
7 character in a string: | 7 | 


/* Look through the string for an uppercase character. */ 
for (lpszUpper = Ipsz; 
!IsCharUpper(*lpszUpper) && IpszUpper != '\@'; 
lpszUpper = AnsiNext(IpszUpper) ); 
/* Return NULL if no uppercase character is found. */ 
if (IpszUpper == '\Q"') 
IpszUpper = NULL; 


See Also IsCharLower 


IsChild eee ess 


BOOL IsChild(hwndParent, hwndChild) 
HWND hwndParent; —_—‘/* handle of parent window if 
HWND hwndChild; -/* handle of child window re! 


The IsChild function tests whether a given window is a child or other direct de- 
scendant of a given parent window. A child window is the direct descendant of a 

| given parent window if that parent window is in the chain of parent v windows lead- 
ing from the original pop-up window to the child window. | 


— 652. IsClipboardFormatAvailable 


Parameters hwndParent | 
Identifies the parent window. 


hwndChild | | 
Identifies the child window to be tested. 


Return Value The return value is nonzero if the child window is a descendant of the parent win- 
| dow. Otherwise, it is zero. 


See Also SetParent 


IsClipboardFormatAvailable [2x | 


BOOL IsClipboardFormatAvailable(uFormat) 
UINT uFormat; /* registered clipboard format aa | 


The IsClipboardFormatA vailable function specifies whether data of a certain 
format exists on the clipboard. 


Parameters uFormat 
Specifies a registered clipboard format. For information about clipboard for- 
mats, see the description of the SetClipboardData function. 


Return Value The return value is nonzero if data of the specified format is on the clipboard. 
Otherwise, the return value is zero. 


Comments This function is typically called during processing of the WM_INITMENU or 
~  WM_INITMENUPOPUP message to determine whether the clipboard contains 
data that the application can paste. If such data is present, the application typically 
enables the Paste command (in its Edit menu). 


See Also CountClipboardFormats, EnumClipboardFormats, GetClipboardFormat- 
Name, GetPriorityClipboardFormat, Becislere upboarchormat 
SetClipboardData 


IsDBCSLeadByte 7 3 Eu 


BOOL IsDBCSLeadByte(bTestChar) 
BYTE bTestChar; /* character to test | 


isDialogMessage 553 


The IsSDBCSLeadByte function determines whether a character is a lead byte, the 
first byte of a character in a double-byte character set (DBCS). 


Parameters § —SbTestChar 
Specifies the character to be tested. 


Return Value The return value is nonzero if the character is a DBCS lead byte. Otherwise, it is 
zero. 
Comments , The language driver for the current language (the language the user selected at 


setup or by using Control Panel) determines whether the character is in the set. If 
_no language driver is selected, Windows uses an internal function. 


Each double-byte character set has a unique set of lead-byte values. By itself, a 
_ lead byte has no character value; together, the lead byte and the following byte rep- 
resent a single character. The second, or following, byte is called a trailing byte. 


See Also GetKeyboardType 


lsDialogMessage 8 —t™S ee Lx] 


BOOL IsDialogMessage(hwndDIg, Ipmsg) 
HWND hwndDig;_ _—s/* handle of dialog box **/ 
MSG FAR* Ipmsg; _‘/* address of structure with message —S>_*/ 


The IsDialogMessage function determines whether the specified message is 1n- 
tended for the given modeless dialog box and, if it is, processes the message. 


Parameters hwndDlg 
| Identifies the dialog box. 


lpmsg 
Points to an MSG structure that contains the message to be checked. The MSG 
structure has the following form: | | 


typedef struct tagMSG {  /* msg */ | 
: HWND ~=hwnd; | om 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
-DWORD = time; 
POINT pt; 
3} MSG; | , 


904 isDigButtonChecked 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the message has been processed. Otherwise, it 1s 
zero. 7 
Comments Although IsDialogMessage is intended for modeless dialog boxes, it can be used 


with any window that contains controls, enabling such windows to provide the 
same keyboard selection as in a dialog box. 


When IsDialogMessage processes a message, it checks for keyboard messages 
and converts them into selection commands for the corresponding dialog box. For 
example, the TAB key, when pressed, selects the next control or group of controls, 
and the DOWN ARROW key, when pressed, selects the next control in a group. 


If a message is processed by IsDialogMessage, it must not be passed to the 
TranslateMessage or DispatchMessage function. This is because IsDialog- 
Message performs all necessary translating and dispatching of messages. 


IsDialogMessage sends WM_GETDLGCODE messages to the dialog box proce- 
dure to determine which keys should be processed. 


IsDialogMessage can send DM_GETDEFID and DM_SETDEFID messages to 

the window. These messages are defined in the WINDOWS.H header file as 
WM_USER and WM_USER+1, so conflicts are possible with application-defined — 
messages having the same values. 


See Also DispatchMessage, SendDlgItemMessage, TranslateMessage 


IsDIgButtonChecked rex | 


UINT IsDigButtonChecked(hwndDlg, idButton) 
HWND hwnaDieg; /* handle of dialog box + 
int idButton; _ /* button identifier */ 


The IsDlgButtonChecked function determines whether a button has a check mark 
- next to it and whether a three-state button is grayed, checked, or neither. 


Parameters hwndDlg | 
| Identifies the dialog box that contains the button. 


idButton | 
Specifies the identifier of the button. 


Return Value 


- Comments 


See Also — 


Islconic 555 


The return value is nonzero if the specified button is checked, 0 if it is not, or —1 if 
the hwndDlg parameter is invalid. For three-state buttons, the return value is 2 if 
the button is grayed, | if the button is checked, 0 if it is unchecked, or —1 if 
hwndDi/g is invalid. | 


The IsDlgButtonChecked function sends a BM_GETCHECK message to the 
button. | = 


CheckDlgButton, CheckRadioButton 


IsGDIObject | ae [ 3.1 | 


BOOL IsGDIObject(hobj) 


-HGDIOBJ hobj; 


Parameters 


Return Value 


/* handle of a menu */ 


The IsGDIObject function determines whether the specified handle is not the 
handle of a graphics device interface (GDI) object. | 


hobj : 
_ Specifies a handle to test. 


The return value is nonzero if the handle may be the handle of a GDI object. It is 
zero if the handle is not the handle of a GDI object. 


An application cannot use IsGDIObject to guarantee that a given handle is to a 


~ Comments 
GDI object. However, this function can be used to guarantee that a given handle is 
not to a GDI object. 
See Also GetObject 
Isleonic [ 2.x | 
BOOL IsIconic(hwnd) 
HWND hwnd; /* handle of window */ 


The IsIconic function determines whether the given window is minimized (iconic). 


006 IsMenu 


Parameters hwnd 
Identifies the window. 


Return Value The return value is nonzero if the window is minimized. Otherwise, it is zero. 


See Also CloseWindow, IsZoomed 


IsMenu Bal 


BOOL IsMenu(hmenu) 
HMENU hmenu; /* handle of menu */ 


The IsMenu function determines whether the given handle is a menu handle. 


Parameters hmenu 
Identifies the handle to be tested. 


Return Value The return value is zero if the handle is definitely not a menu handle. A nonzero re- 
turn value does not guarantee that the handle is a menu handle, however; for non- 
zero return values, the application should conduct further tests to verify the handle. 


Comments An application should use this function only to ensure that a given handle is not a 
| menu handle. 
See Also CreateMenu, CreatePopupMenu, DestroyMenu, GetMenu 


IsRectEmpty = _ 


BOOL IsRectEmpty(/prc) 
const RECT FAR* [prc; /* address of structure with rectangle cd 


The IsRectEmpty function determines whether the specified cine 1S empty. 


A «lel sf LA 
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Parameters Ipre 
Points to a RECT structure that contains the coordinates of the rectangle. The 
RECT structure has the following form: 
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typedef struct tagRECT { /* ro */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the M. icrosoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the rectangle is empty. Otherwise, it is zero. 
Example | The following example uses the IsRectEmpty function to determine whether a 
rectangle is empty and then displays a message box giving the status of the 
rectangle: | | | | 
RECT rc; | 


if (IsRectEmpty((LPRECT) &rc)) 
MessageBox(hwnd, "Rectangle is empty.", 
"Rectangle Status", MB_OK); 
else . 
MessageBox(hwnd, "Rectangle is not empty."”, 
"Rectangle Status", MB_OK); 


IsTask -¥ orks 


BOOL IsTask(htask) 
HTASK htask; /* handle of task *«/ 


The IsTask function determines whether the given task handle is valid. 


Parameters htask 
Identifies a task. 


Return Value | The return value is nonzero if the task handle is valid. Otherwise, it is zero. 
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IsWindow 


[ 2.x | 


~BOOL IsWindow(hwnd) 


HWND hwnd; 


Parameters 


Return Value 


See Also 


/* handle of window */ 


The IsWindow function determines whether the given window handle is valid. 


hwnd 
Identifies a window. 


The return value is nonzero if the window handle is valid. Otherwise, it is zero. 


| IsWindowEnabled, IsWindow Visible 


IsWindowEnabled | _ [ 2.x | 


BOOL IsWindowEnabled(hwnd) , 


~HWND hwnd; 


Parameters 


Return Value 
Comments 


See Also 


/* handle of window to tes **/ 


The IsWindowEnabled function determines whether the given window is enabled 
for mouse and keyboard input. 


hwnd 
Identifies the window. 


The return value is nonzero if the window is enabled. Otherwise, it is zero. 
A child window receives input only if it is both enabled and visible. 


IsWindow, IsWindowVisible 


E 


BOOL IsWindowVisible(iwnd) 


HWND hwnd; 


/* handle of window to test  */ 


The IsWindow Visible function determines the visibility state of the given 
window. 
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Parameters hwnd 
| Identifies the window. 


Return Value The return value is nonzero if the specified window is visible on the screen (has 
| the WS_ VISIBLE style bit set). The return value is zero if the window is not vis- 

ible. Because the return value reflects the value of the window’s WS_VISIBLE 
flag, it may be nonzero even if the window is totally obscured by other windows. 


Comments A window possesses a visibility state indicated by the WS_ VISIBLE style bit. 
When this style bit is set, the window is displayed and subsequent drawing into the 
window is displayed as long as the window has the style bit set. 


Any drawing to a window that has the WS_ VISIBLE style will not be displayed if 
the window is covered by other windows or is clipped by its parent window. 


See Also Show Window 


IsZoomed [ 2.x | 


BOOL IsZoomed(hwnd) | 
HWND hwnd; /* handle of window */ 


The IsZoomed function determines whether the given window is maximized. 


Parameters : hwnd 
Identifies the window. 


Return Value The return value is nonzero if the window is maximized. Otherwise, it is zero. 


See Also IsIconic 


JournalPlaybackProc = waht e ek ae EXE 


LRESULT CALLBACK J ournalPlaybackProc(code, ale [Param) 
int code; /* process-message flag oT 
WPARAM wParam; /* undefined — _ +] 
LPARAM /Param; /* address of structure for message */ 
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The JournalPlaybackProc function is a library-defined callback function that a 
library can use to insert mouse and keyboard messages into the system message 
queue. Typically, a library uses this function to play back a series of mouse and 
keyboard messages that were recorded earlier by using the JournalRecordProc 
function. Regular mouse and keyboard input is disabled as long as a Journal- 
PlaybackProc function is installed. 


* 


Parameters code 
| Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If this parameter is less than zero, the callback func- 
- tion should pass the message to CallNextHookEx without further processing. 


wParam | 
Specifies a NULL value. 


lParam 
Points to an EVENTMSG structure that represents the message being 
processed by the callback function. The EVENTMSG structure has the follow- 
ing form: 


typedef struct tagEVENTMSG { /* em */ 
~ UINT message; 
UINT paramL; 
UINT paramH; 
DWORD time; 
} EVENTMSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The callback function should return a value that represents the amount of time, in 
clock ticks, that the system should wait before processing the message. This value 
can be computed by calculating the difference between the time members of the 
current and previous input messages. If the function returns zero, the message is 
processed immediately. | 


Comments The JournalPlaybackProc function should copy an input message to the Param 
. parameter. The message must have been recorded by using a J OuFHaTsecoruhroc 
callback function, which should not modify the message. | 


Once the function returns control to the system, the message continues to be 
processed. If the code parameter is HC_SKIP, the filter function should prepare to 


return ine ICA recorded CVEiit mcssage Oll its LCA Call. 
This callback function should reside in a namic link library. 


An sop licaion must install the callback function by specifying the | 
WH_JOURNALPLAYBACK filter type and the procedure-instance address of the 
callback function in a call to the SetWindowsHookEx function. 


JournalRecordProc 561 


JournalPlaybackProc is a placeholder for the library-defined function name. The 
actual name must be exported by including it in an EXPORTS statement in the 
library’s module-definition file. | 


See Also CallNextHookEx, JournalRecordProc, SetWindowsHookEx 


JournalRecordProc se EXE 


LRESULT CALLBACK JournalRecordProc(code, wParam, lParam) 
int code; /* process-message flag id 
WPARAM wParam; /* undefined | 
LPARAM /Param; /* address of structure for message */ 


The JournalRecordProc function is a library-defined callback function that re- 
cords messages that the system removes from the system message queue. Later, a 
library can use a JournalPlaybackProc function to play back the messages. 


Parameters code 
Specifies whether the callback function oil process the message or call the 
CallNextHookEx function. If this parameter is less than zero, the callback func- 
~ tion should pass the message to CallNextHookEx without further processing. 


wParam 
Specifies a NULL value. 


[Param 
Points to an MSG structure. The MSG structure has the etonowne form: 


typedef struct tagMSG {  /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The callback function should return zero. 
Comments A JournalRecordProc callback function should copy but not modify the mes- 


sages. After control returns to the system, the message continues to be processed. 
The callback function does not require a return value. | 
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This callback function must be in a dynamic-link library. — 


An application must install the callback function by specifying the 
WH_JOURNALRECORD filter type and the procedure-instance address of the 
callback function in a call to the SetWindowsHookEx function. 


JournalRecordProc is a placeholder for the library- -defined function name. The 
actual name must be exported by including it in an EXPORTS statement in the 
library’s module-definition file. 


See Also CallNextHookEx, JournalPlaybackProc, SetWindowsHookEx 


KeyboardProc [3.1 | 


LRESULT CALLBACK KeyboardProc(code, wParam, lParam) 

int code; __. /* process-message flag | 
WPARAM wParam; /* virtual-key code **/ 
LPARAM /Param; /* keyboard-message information ep 


The KeyboardProc function is a library-defined callback function that the system 
calls whenever the application calls the GetMessage or Peek Message function 
and there is a WM_KEYUP or WM_KEYDOWN keyboard message to process. 


Parameters code 
Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If this value is HC_NOREMOVE, the application 
is using the PeekMessage function with the PM_NOREMOVE option, and the 
message will not be removed from the system queue. If this value is less than 
zero, the callback function should pass the message to CallNextHookEx 
without further processing. 


wParam 
Specifies the virtual-key code of the given key. 


lParam 
Specifies the repeat count, scan code, extended key, previous key state, context 
code, and key-transition State, as shown in the rooming table. (Bit 0 is the low- 


order bit): 
Bit Description 
0-15 Specifies the repeat count. The value is the number of times the keystroke 


is repeated as a result of the user holding down the key. 


16-23 Specifies the scan code. The value depends on the original equipment — | 
manufacturer (OEM). 
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Bit Description room 
) Specifies whether the key is an extended key, such as a function key ora 
key on the numeric keypad. The value is 1 if it is an extended key; other- 
wise, it is 0. 


25-26 Not used. 
27-28 Used internally by Windows. 


29 ~~. _~__ Specifies the context code. The value is 1 if the ALT Key is held down 
while the key is pressed; otherwise, the value is 0. 

30 Specifies the previous key state. The value is 1 if the key is down before 
the message is sent, or it is 0 if the key is up. | 

31 Specifies the key-transition state. The value is 1 if the key is being re- 


leased, or it is 0 if the key is being pressed. 


Return Value The callback function should return 0 if the message should be processed by the 
| system; it should return 1 if the message should be discarded. : : 


Comments This callback function must be in a dynamic-link library. 


An application must install the callback function by specifying the . 
WH_KEYBOARD filter type and the procedure-instance address of the callback 
function in a call to the SetWindowsHookEx function. 


KeyboardProc is a placeholder for the library-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the library’s — 
module-definition file. 


See Also | CallNextHookEx, GetMessage, PeekMessage, SetWindowsHookEx 


KillTimer Be 


BOOL KillTimer(hwnd, idTimer) | | 
HWND hwnd; /* handle of window that installed timer ss) 
UINT idTimer: /* timer identifier | af 


The KillTimer function removes the specified timer. Any pending WM_TIMER 
_ messages associated with the timer are removed from the message queue. 


‘Parameters = = hwnd — | 
_* Identifies the window associated with the timer to be removed. This must be the 
same value basset as the hwnd parameter of the SetTimer function that created 
the timer. , | 
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idTimer 
Identifies the timer to be removed. If the application called SetTimer with the 
hwnd parameter set to NULL, this parameter must be the timer identifier re- 
turned by SetTimer. If the hwnd parameter of SetTimer was a valid window 
handle, this parameter must be the value of the idTimer parameter passed to Set- 
Timer. | 


Return Value The return value is nonzero if the function is successful. It is zero if the KillTimer 
7 function could not find the specified timer. 


See Also SetTimer 


_Iclose _. Lex] 


HFILE _ Iclose(hf) 
HFILE hf; /* handle of file to close */ 


The _Iclose function closes the given file. As a result, the file is no longer availa- 
ble for reading or writing. 


Parameters hf 


Identifies the file to be closed. This handle is returned by the function that 
created or last opened the file. 


Return Value The return value is zero if the function is successful. Otherwise, it is 
HFILE_ERROR. 
Example The following example copies a file to a temporary file, then closes both files: 


int cbRead; 
~PBYTE pbBuf; 


/* Allocate a buffer for file I/0. */ 
pbBuf = (PBYTE) LocalAlloc(LMEM_FIXED, 2048); 
—/*® Copy the input file to the temporary file. */ 
do { | 
cbRead = _lread(hfReadFile, pbBuf, 2048); 
_Iwrite(hfTempFile, pbBuf, cbRead); 
} while (cbRead != Q@); 


/* Free the buffer and close the files. */ 
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LocalFree((HLOCAL) pbBuf); 


_lclose(hfReadFile); 
_Iclose(hfTempFile); 


See Also -_lopen, OpenFile 


_Icreat | a ce? Tea] 


HFILE _Icreat(/pszFilename, fnAttribute) 
LPCSTR I[pszFilename; /* address of file to open | 
int fnAttribute; /* file attributes */ 


The _lcreat function creates or opens a specified file. If the file does not exist, the 
function creates a new file and opens it for writing. If the file does exist, the func- 
tion truncates the file size to zero and opens it for reading and writing. When the 
function opens the file, the pointer is set to the beginning of the file. 


Parameters ier lename : 
| Points to a null-terminated string that names the file to be opened. The string | 
must consist of characters from the Windows character set. 


fnAttribute 
Specifies the file attributes. This parasites must be one of the following wales: 


Value Meaning | 
0 Normal; can be read or written without restriction. 
1 Read-only; cannot be opened for writing. 
oe Hidden; not found by directory search. 
3 System; not found by directory search. 
Return Value The return value: isa file handle if the function 1 is siecesstul: Otherwise, it is 
HFILE_ERROR. : 
Comments | ce this function carefully. It is possible to open any file, even one that has al- 


ready been opened by another function. | 


Example The following example u uses the _ lcreat function to open a temporary file: 


~ HFILE hfTempFile;. i 
char szBufl144]; 
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/* Create a temporary file. */— 
GetTempFileName(@, "tst", @, szBuf); 
hfTempFile = _lcreat(szBuf, @); 

if (hfTempFile == HFILE_ERROR) { 


ErrorHandler(); 
} 
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int CALLBACK LibMain(hinst, wDataSeg, cbHeapSize, lpszCmdLine) 
*/ 


HINSTANCE hinst; /* handle of library instance 

WORD wDataSeg; /* library data segment sa | 
WORD cbHeapSize; /* default heap size sa | 
LPSTR [pszCmdLine; /* command-line arguments */ 


The LibMain function is called by the system to initialize a dynamic-link library 
(DLL). A DLL must contain the LibMain function if the library is linked with the 
file LIBENTRY.OBJ. 


Parameters hinst 
Identifies the instance of the DLL. 


wDataSeg 
Specifies the value of the data segment (DS) register. 


cbHeapSize 
Specifies the size of the heap defined in the module-definition file. (The 
LibEntry routine in LIBENTRY.OB3J uses this value to initialize the local heap.) 
lpszCmdLine 
Points to a null-terminated string specifying command-line information. This 
parameter is rarely used by DLLs. | 


Return Value | The function should return 1 if it is successful. Otherwise, it should return 0. 


Comments The LibMain function is called by LibEntry, which is called by Windows when 
the DLL is ioaded. The LibEntry routine is provided in the LIBENTR Y.OBJ mod- 
ule. LibEntry initializes the DLL’s heap (if a HEAPSIZE value is specified in the 
DLL’s module-definition file) before calling the LibMain function. 


LibMain 


Example | The following example shows a typical LibMain function: 


int CALLBACK LibMain(HINSTANCE hinst, WORD ee WORD cbHeap, 
LPSTR IpszCmdLine ) 

{ | : 

HGLOBAL hgb1iClassStruct; 

LPWNDCLASS IpClassStruct; 

static HINSTANCE hinstLib; 


/* Has the library been initialized yet? */ 
if (hinstLib == leisy { 


hgb1iClassStruct = GlobalAlloc(GHND, sizeof (WNDCLASS)); - 
if (hgbiClassStruct != NULL) { 
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TpClassStruct = (LPWNDCLASS) Global Lock(hgbIClassStruct) | 


if (iptlassseruct f= NULL) { 
/* Define the class attributes. */ 


IpClassStruct->style = CS_HREDRAW | CS_VREDRAW | — 
CS_DBLCLKS | CS_GLOBALCLASS; 
IpClassStruct->1IpfnWndProc = DllWndProc; 
TpClassStruct->cbWndExtra = @; 
IpClassStruct->hInstance = hinst; 
IpClassStruct->hIcon = NULL; 
— JpClassStruct->hCursor = LoadCursor(NULL, IDC_ARROW) ; 
— TpClassStruct->hbrBackground = 
(HBRUSH) (COLOR_WINDOW + 1); 
IpClassStruct->1lpszMenuName = NULL; 
IpClassStruct->IpszClassName = "MyClassName"; 


hinstLib = (RegisterClass(IpClassStruct)) 2 
hinst. : NULL; 


GlobalUnlock(hgbiClassStruct); 
} 7 


GlobalFree(hgb1ClassStruct); 
a 
ee 7 
return (hinstLib ? 1: @); /* return 1 = success; @ = fail */ 


SeeAlso  -—GloballAlloc, GlobalFree, GlobalLock, GlobalUnlock, WEP 


6-568 LimitEmsPages 


LimitEmsPages 


void LimitEmsPages(cAppKB) 


DWORD cAppKB; 


LineDDA 


/* amount of expanded memory available to aeplicanon */ 


In Windows version 3.1, this function is obsolete and does nothing. 


void LineDDA (nXStart, nYStart, nXEnd, nYEnd, Inddaprc, lParam) 


int nXStart; /* x-coordinate of line beginning i 
int nYStart; /* y-coordinate of line beginning | 
int nXEnd; /* x-coordinate of line end **/ 
int nYEnd; /* y-coordinate of line end / 
LINEDDAPROC Inddaprc; /* address of callback function **/ 
LPARAM /Param; /* address of application-defined data */ 
The LineDDA function computes all successive points in a line specified by 
starting and ending coordinates. For each point on the line, the system calls an 
application-defined callback function, specifying the coordinates of that point. 
Parameters nXStart 
Specifies the logical x-coordinate of the first point. 
nYStart 
Specifies the logical y-coordinate of the first point. 
nXEnd 


Specifies the logical x-coordinate of the endpoint. This endpoint is not part of 
the line. 


nYEnd 
Specifies the logical y-coordinate of the endpoint. This endpoint 1 is not part of 
the line. 


Inddaprc 
Specifies the procedure-instance address of the application- defined callback 
function. The address must have been created by using the MakeProcInstance 
function. For more information about the callback function, see the description 
of the LnneDDAProc callback function. 


[Param 
Points to 32 bits of application-defined data that is passed to the callback 
function. | 
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Return Value This function does not return a value. 


Example : The following example uses the LineDDA function to draw a dot every two 
spaces between the beginning and ending points of a line: 


/* Callback function * / 
void CALLBACK DrawDots(int xPos, int yPos, LPSTR Iphdc) 
static short cSpaces = 1; | 
if (cSpaces sa 3) { 
/* Draw a black dot. */ 
SetPixel(*(HDC FAR*) lphdc, xPos, yPos, @); 
/* Initialize the space count. */ 
’ cSpaces = 1; 


else 
cSpacest+; 


See Also LineDDAProc, MakeProcInstance 


LineDDAProc a [8A 


void CALLBACK LineDDAProc(xPos, yPos, [pData) 


int xPos; | /* x-coordinate of current position */ 
int yPos; /* y-coordinate of current position **/ 


LPARAM [pData;_—si/* address of application-defined data */ 


_ The LineDDAProc function is an application-defined callback function that — 
processes coordinates from the LineDDA function. 


Parameters xPos 
| Specifies the x- -coordinate of the current point. 


-yPos 
Specifies the y- -coordinate of the current point. 


[pData 
Points to the sppheeOn ee data. 
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Return Value 


Comments 


See Also 


Linelo 


This function does not return a value. 


An application must register this function by passing its address to the LineDDA 
function. 


LineDDAProc is a placeholder for the application-defined function name. The ac- 


tual name must be exported by including it in an EXPORTS statement in the ap- 
plication’s module-definition file. 


LineDDA 


BOOL LineTo(hdc, nXEnd, nYEnd) 


HDC hdc; | 
int nXEnd; 
int nYEnd; 


Parameters 


Return Value 


Example 


/* handle of device context */ 
/* x-coordinate of line endpoint */ 
/* y-coordinate of line endpoint */ 


The LineTo function draws a line from the current position up to, but not includ- 
ing, the specified endpoint. The function uses the selected pen to draw the line and 
sets the current position to the coordinates (nXEnd,nYEnd). 


hdc 7 
Identifies the device context. 


nXEnd | 
Specifies the logical x-coordinate of the line’s endpoint. 


nYEnd | 
Specifies the logical y-coordinate of the line’s endpoint. 


The return value is nonzero if the function is successful. Otherwise, itis zero. | 


The following example sets the current position by using the MoveTo function 
before calling the LineTo function. The example uses POINT structures to store 
the coordinates. 


HDC hdc; 
POINT ptStart = { 12, 12}; 
POINT ptEnd = { 128, 135 }; 


MoveTo(hdc, ptStart.x, ptStart.y); 
LineTo(hdc, ptEnd.x, ptEnd.y); 


See Also 


_ Ilseek 
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MoveTo 


LONG _llseek(hf, lOffset, nOrigin) 


HFILE hf; 
LONG [Offset; 
int nOrigin; 


Parameters 


Return Value 
Comments 


Example 


/* file handle **/ 
/* number of bytes to move a] 
/* position to move from */ 


The _llseek function repositions the pointer in a previously opened file. 


hf 
Identifies the file. 


lOffset 
Specifies the number of bytes the pointer is to be moved. 


nOrigin 
Specifies the starting position and direction of the ae This parameter must 
be one of the following values: 


Value Meaning 

0 Move the file pointer /Offset bytes from the beginning of the file. 
1 Move the file pointer /Offset bytes from its current position. 

2 Move the file pointer /Offset bytes from the end of the file. 


The return value specifies the new offset, in bytes, of the pointer from the begin- 
ning of the file, if the function is successful. Otherwise, the return value is 


HFILE_ERROR. 


When a file is initially opened, the file pointer is positioned at the beginning of the 
file. The _llseek function permits random access to a file’s contents by moving 
the pointer an arbitrary amount without reading data. 


The following example uses the _llseek function to move the file pointer to the 
end of an existing file: 


HFILE hfAppendFile; 
/* Open the write file. */ 


hfAppendFile = _lopen("append.txt", WRITE); 
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See Also 


LoadAccelerators 


/* Move to the end of the file. */ 


if (_llseek(hfAppendFile, @L, 2) == -1) { 
ErrorHandiler(); 
; | 


_lopen 


HACCEL LoadAccelerators(hinst, lpszTableName) 


HINSTANCE hinst; 


/* handle of module to load from */ 


LPCSTR IpszTableName; /* address of table name | */ 


Parameters 


Return Value 


Comments 


The LoadAccelerators function loads the specified accelerator table. 


hinst 
Identifies an instance of the module whose executable file contains the accelera- 
tor table to be loaded. 


IpszTableName 
Points to a null-terminated string that names the accelerator table to be loaded. 


The return value is the handle of the loaded accelerator table if the function is | 
successful. Otherwise, it is NULL. 


If the accelerator table has not yet been loaded, the function loads it from the given 
executable file. | | 


Accelerator tables loaded from resources are freed automatically when the a 
tion terminates. 
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LoadBitmap [2x | 


HBITMAP LoadBitmap(hinst, [pszBitmap) 
HINSTANCE hinst; /* handle of application instance #/ 
LPCSTR IpszBitmap; /* address of bitmap name if 


The LoadBitmap function loads the specified bitmap resource from the given 
module’s executable file. 


Parameters | hinst 
Identifies the instance of the module whose executable file contains the bitmap 
to be loaded. 7 


lpszBitmap 
Points to a null-terminated string that contains the name of the bitmap resource 
to be loaded. Alternatively, this parameter can consist of the resource identifier 
in the low-order word and zero in the high-order word. The MAKEINT- 
RESOURCE macro can be used to create this value. 


Return Value The return value is the handle of the specified bitmap if the function is successful. 
Otherwise, it is NULL. | 


Comments If the bitmap pointed to by /pszBitmap does not exist or if there is insufficient 
memory to load the bitmap, the function fails. | 


The application must call the DeleteObject function to delete each bitmap handle 
returned by the LoadBitmap function. This also applies to the following prede- 
fined bitmaps. 


An application can use the LoadBitmap function to access the srsehiied bitmaps 
used by Windows. To do so, the application must set the hinst parameter to NULL 
and the /pszBitmap parameter to one of the following values: 


OBM_BTNCORNERS 
OBM_BTSIZE 
OBM_CHECK 
OBM_CHECKBOXES 
OBM_CLOSE 
OBM_COMBO 
OBM_DNARROW 
OBM_DNARROWD 
OBM_DNARROWI 
OBM_LFARROW 
OBM_LFARROWD > 
OBM_LFARROWI 
OBM_MNARROW 
OBM_OLD_CLOSE 
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OBM_OLD_DNARROW 
OBM_OLD_LFARROW 
OBM_OLD_REDUCE 
OBM_OLD_RESTORE 
OBM_OLD_RGARROW 
OBM._OLD_UPARROW 
OBM_OLD_ZOOM 
OBM_REDUCE 
OBM_REDUCED 
OBM_RESTORE 
OBM_RESTORED 
OBM_RGARROW 
OBM_RGARROWD 
OBM_RGARROWI 
OBM_SIZE 
OBM_UPARROW 
OBM_UPARROWD 
OBM_UPARROWI 
OBM_ZOOM 
OBM_ZOOMD 


Bitmap names that begin with OBM_OLD represent bitmaps used by Windows 
versions earlier than 3.0. 


The bitmaps identified by OBM_DNARROWI, OBM_LFARROWI, | | 
OBM_RGARROWI, and OBM_UPARROW/I are new for Windows 3.1. These 
bitmaps are not found in device drivers for previous versions of Windows. 


Note that for an application to use any of the OBM_ constants, the constant 
OEMRESOURCE must be defined before the WINDOWS.H header file is in- 
cluded. 


The following shows the appearance of each of the OBM_ bitmaps. 
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See Also DeleteObject 

LoadCursor 
HCURSOR LoadCursor(hinst, pszCursor) 3 : 

HINSTANCE hinst; /* handle of application instance */ 

LPCSTR pszCursor; /* cursor-name string or cursor resource identifier ony 


The LoadCursor function loads the specified cursor resource from the executable 
file associated with the given application instance. 
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Parameters 


Return Value 


Comments 


See Also 


hinst 


be loaded. 


pszCursor 


Identifies an instance of the module whose executable file contains the cursor to 


Points to a null-terminated string that contains the name of the cursor resource 
to be loaded. Alternatively, this parameter can consist of the resource identifier 
in the low-order word and zero in the high-order word. The MAKEINT- 
RESOURCE macro can be used to create this value. 


The return value is the handle of the newly loaded cursor if the function is success- 
ful. Otherwise, it is NULL. 


The function loads the cursor resource only if it has not been loaded; otherwise, it 
retrieves a handle of the existing resource. The LoadCursor function returns a 
valid cursor handle only if the pszCursor parameter points to a cursor resource. If 
pszCursor points to any type of resource other than a cursor (such as an icon), the 
return value will not be NULL, even though it is not a valid cursor handle. 


An application can use the LoadCursor function to access the predefined cursors 
used by Windows. To do this, the application must set the hinst parameter to 
NULL and the pszCursor parameter to one the following values: 


Value 


IDC_ARROW 
IDC_CROSS 
IDC_IBEAM 
IDC_ICON 
IDC_SIZE 
IDC_SIZENESW 


IDC_SIZENS 
IDC_SIZENWSE 


IDC_SIZEWE 
IDC_UPARROW 
IDC_WAIT 


Meaning 


Standard arrow cursor. 

Crosshair cursor. 

Text I-beam cursor. 

Empty icon. 

A square with a smaller square inside its lower-right corner. 


Double-pointed cursor with arrows pointing northeast and south- 
west. 


Double-pointed cursor with arrows pointing north and south. 


Double-pointed cursor with arrows pointing northwest and south- 
east. 


Double-pointed cursor with arrows pointing west and east. 
Vertical arrow cursor. 
Hourglass cursor. 


It is not necessary to destroy these system cursors. An application should use the 
DestroyCursor function to destroy any private cursors it loads. | 


DestroyCursor, SetCursor, ShowCursor 
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Loadicon 


[ 2x | 


HICON LoadIcon(hinst, pszicon) 


HINSTANCE hinst; 


LPCSTR pszlIcon; 


Parameters 


Return Value 


| Comments 


/* handle of application instance | 
/* icon-name string or icon resource identifier */ 


The LoadIcon function loads the specified icon resource from the executable file 
associated with the given application instance. 


—hinst 


Identifies an instance of the module whose executable file contains the icon to 
be loaded. This parameter must be NULL when a system icon is being loaded. 


pszlcon 
Points to a null-terminated string that contains the name of the icon resource to 
be loaded. Alternatively, this parameter can consist of the resource identifier 
in the low-order word and zero in the high-order word. The MAKEINT- 
RESOURCE macro can be used to create this value. 


The return value is the handle of the newly loaded icon if the function is success- 
ful. Otherwise, it is NULL. 


This function loads the icon resource only if it has not been loaded; otherwise, it 
retrieves a handle of the existing resource. 


An application can use the LoadIcon function to access the predefined icons used 
by Windows. To do this, the application must set the hinst parameter to NULL and 
the pszicon parameter to one of the following values: 


Value | Meaning 

IDI_APPLICATION Default application icon. 

IDI_ASTERISK Asterisk (used in informative messages). 
IDI_EXCLAMATION Exclamation point (used in warning messages). 
IDI_HAND Hand-shaped icon (used in serious warning messages). 
IDI_QUESTION ~ Question mark (used in prompting messages). | | 


It is not necessary to destroy these system icons. An application should use the 
DestroylIcon function to destroy any private icons it loads. 
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IDIL_APPLICATION 
IDI_HAND 
IDI_QUESTION 


IDIL_EXCLAMATION 


IDLASTERISK 


See Also DestroyIcon, DrawIcon 
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HINSTANCE LoadLibrary(/pszLibFileName) 7 
LPCSTR IpszLibFileName; /* address of name of library file | 


The LoadLibrary function loads the specified library module. 


Parameters lpszLibFileName 
Points to a null-terminated string that names the library file to be loaded. If the 
string does not contain a path, Windows searches for the library in this order: 
1. The current directory. 


2. The Windows directory (the directory containing WIN. COM): the Get- 
_ WindowsDirectory function retrieves the path of this directory. 


3. The Windows system directory (the directory containing such system files as 
GDI.EXE); the GetSystemDirectory function retrieves the path of this 
directory. 


4. The directory containing the executable file for the current task: the Get- 
ModuleFileName function retrieves the path of this directory. 


5. The directories listed in the PATH environment variable. 


6. The list of directories mapped in a network. 


Return Value The return value is the instance handle of the loaded library module if the function 
is successful. Otherwise, it is an error value less than HINSTANCE_ERROR. 


Errors 


Comments 


Example 
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If the function fails, it returns one of the following error values: 


Value Meaning 
0 System was out of memory, executable file was corrupt, or relocations were 
invalid. 
2 File was not found. 
3 Path was not found. 
5 Attempt was made to dynamically link to a task, or there was a sharing or 
network-protection error. | 
6 Library required separate data segments for each task. 
8 There was insufficient memory to start the application. 
10 Windows version was incorrect. 
11 Executable file was invalid. Either it was not a Windows application or 
there was an error in the EXE image. : : 
12 Application was designed for a different operating system. 
13 Application was designed for MS-DOS 4.0. | 
14 Type of executable file was ‘unknown. 
15 Attempt was made to load a real-mode appueson (developed for an earlier: 
version of Windows). 
16 Attempt was made to load a second instance of an executable file contain- 
_. ing multiple data segments that were not marked read-only. 3 
19 Attempt was made to load a compressed executable file. The file must be 
| decompressed before it can be loaded. 
20 Dynamic-link library (DLL) file was invalid. One of the DLLs required: to 
run this application was corrupt. 
21 | Application requires Microsoft Windows 32-bit extensions. 


If the module has been loaded, LoadLibrary increments (increases by one) the 
module’s reference count. If the module has not been loaded, the function loads it 
from the specified file. | 


LoadLibrary increments the reference count for a library module each time an ap- 
plication calls the function. When it has finished using the module, the application 
should use the FreeLibrary function to decrement (decrease by one) the reference 
count. 


An application can use the GetProcAddress function to access functions in a 


library that was loaded using head Library. 


z The following example uses the Laadl ibrary function to load the Tool Helper | 


Library TOOLHELP.DLL and the FreeLibrary function to free it: 


HINSTANCE hinstToolHelp = LoadLibrary ("TOOLHELP. DLL"), 
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if ((UINT) hinstToolHelp > 32) { 
. /* use GetProcAddress to use TOOLHELP functions */ 
} 
else { 
ErrorHandler(); 
} 


if (CUINT) hinstToolHelp > 32) 
FreeLibrary(hinstToolHelp); /* free TOOLHELP.DLL x / 


See Also FreeLibrary, GetProcAddress 


LoadMenu _ EG 


HMENU LoadMenu(hinst, IpszMenuName) 
HINSTANCE hinst; /* handle of application instance | */ 
LPCSTR ipscMenuName; /* menu-name string or menu resource identifier | 


The LoadMenu function loads the specified menu resource from the executable 
file associated with the given application instance. 


Parameters “hinst 


Identifies an instance of the module whose executable file contains the menu to 
be loaded. 


lpszMenuName 
Points to a null-terminated string that contains the name of the menu resource 
to be loaded. Alternatively, this parameter can consist of the resource identifier 
in the low-order word and zero in the high-order word. The MAKEINT- 
RESOURCE macro can be used to create this value. 


Return Value The return value is the handle of the menu resource if the function is successful. 


Otherwise, it is NULL. 


Comments Before exiting, an application must free system resources associated with a menu 
if the menu is not assigned to a window. An application frees a menu by calling 
the DestroyMenu function. 


Example The following example loads a menu resource, and then assigns the menu to a 
window: 


See Also 
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HMENU hmenu; 


hmenu = LoadMenu(hinst, "ColorMenu"); 
SetMenu( hwnd, hmenu); 


DestroyMenu, LoadMenuIndirect, SetMenu 


LoadMenulndirect Be oe 


HMENU LoadMenuIndirect(lpmith) 
const void FAR* [pmith; /* address of menu template ‘| 


Parameters 


Return Value 


The LoadMenulndirect function loads the specified menu template in memory. 
A menu template is a header followed by a collection of one or more MENU- 
ITEMTEMPLATE structures, each of which may contain one or more menu 
items and pop-up menus. , 


[pmith 
Points to a menu template, which consists of a menu-template header and one 
or more menu item templates. The menu template header consists of aMENU- — 
ITEMTEMPLATEHEADER structure, which has the following form: 


typedef struct { /* mith */ 
UINT versionNumber; 
UINT offset; 

} MENUITEMTEMPLATEHEADER; 


Each menu item template consists of aMENUITEMTEMPLATE structure. 
The MENUITEMTEMPLATE structure has the following form: 


typedef struct { /* mit */ 
UINT mtOption; 
UINT mtID; 
- char mtString[1]; 
J MENUITEMTEMPLATE; 


For a full description of these two structures, see the Microsoft Windows Pro- 
| gran! ’s Reference, Volume 3. | | 


The return value i is the handle of a menu if the Ancien is succesfull Otherwise, it 
As NULL. 
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Comments Before exiting, an application must free system resources associated with a menu 
| . if the menu is not assigned to a window. An appicanion frees a menu by calling 
the DestroyMenu function. 


Example The following example retrieves a menu handle for a menu template resource that 
has been loaded into memory, gives the menu handle to a window, and then un- 
locks and frees the resource: 


HRSRC hrsrcResInfo; 
HGLOBAL hglbResMenu; 
char FAR* 1pResMenu; 
HMENU hmenu; 


case IDM_NEWMENU: 
hrsrcResInfo = FindResource(hinst, "DynaMenu", RT_MENU); 
hglbResMenu = LoadResource(hinst, hrsrcResInfo); 
]TpResMenu = LockResource(hglbResMenu) ; 
hmenu = LoadMenuIndirect(1pResMenu) ; 


DestroyMenu(GetMenu(hwnd) ); 
SetMenu(hwnd, hmenu); 


UnlockResource(hglbResMenu) ; 
FreeResource(hglbResMenu) ; 


break; 


See Also DestroyMenu, LoadMenu, SetMenu 


LoadModule oe a - 


HINSTANCE LoadModule(/pszModuleName, IpvParameterBlock) 
LPCSTR IpszModuleName; /* address of filename to load 1 
LPVOID I[pvParameterBlock; /* address of parameter block for new module yf 


The LoadModule function loads and executes a Windows application or creates a 
new instance of an existing Windows application. 


Parameters InszModuleName 
Points to a null-terminated string that contains the complete filename (including 
the file extension) of the application to be run. If the string does not contain a 
path, Windows searches for the executable file in this order: 


1. The current directory. 
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2. The Windows directory (the directory containing WIN.COM), whose path 
the GetWindowsDirectory function retrieves. 


3. The Windows system directory (the directory containing such system files as 
GDI.EXE), whose path the GetSystemDirectory function retrieves. 


4. The directory containing the executable file for the current task; the Get- 
ModuleFileName function obtains the path of this directory. 


5. The directories listed in the PATH environment variable. 
6. The list of directories mapped in a network. 


[pvParameterBlock 
Points to an application- -defined LOADPARMS structure that defines the new 
application’s parameter block. The LOADPARMS structure has the following 
form: 


struct _LOADPARMS { 


WORD segEnv;: /* child environment */ 
LPSTR lpszCmdLine; /* child command tail */ 
UINT FAR* 1pShow; /* how to show child #*/ 
UINT FAR* 1pReserved; /* must be NULL * / 
} LOADPARMS; | 
Member Description 
segEnv Specifies whether the child application receives a copy of 


the parent application’s environment or a new environment — 
created by the parent application. If this member is zero, the 

child application receives an exact duplicate of the parent ap- 
plication’s environment block. If the member is nonzero, the 
value entered must be the segment address of a memory ob- 
ject containing a copy of the new environment for the child 
application. 


IpszCommandLine —_ Points to a null-terminated string that specifies the command 
line (excluding the child application name). This string must 
not exceed 120 characters. If there is no command line, this 
member must point to a zeroctengnn string (it cannot be set 

| to NULL). 

IpShow Points to an array containing two 16-bit values. The first : 
value must always be set to two. The second value specifies 
how the application window is to be shown. For a list of the 
acceptable values, see the description of the nCmdShow pa- 
rameter of the ShowWindow function. _ | 


IpReserved Reserved; must be NULL. 


Return Value The return value is the instance handle of the loaded module if the function 
| cae is successful. If the function fails, it returns an error value less than 
HINSTANCE_ERROR. 
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Errors 


Comments 


Example 


If the function fails, it returns one of the following error values: 


Value 


0 


2 
3 


21 


Meaning 

System was out of memory, executable file was corrupt, or relocations were 
invalid. 

File was not found. 

Path was not found. 


Attempt was made to dynamically link to a task, or there was a sharing or 
network-protection error. 


Library required separate data segments for each task. 
There was insufficient memory to start the application. 
Windows version was incorrect. 


Executable file was invalid. Either it was not a Windows application or 
there was an error in the .EXE image. 


Application was designed for a different operating system. 


Application was designed for MS-DOS 4.0. 
Type of executable file was unknown. 


Attempt was made to load a real-mode application (developed for an earlier 
version of Windows). 


Attempt was made to load a second instance of an executable file contain- 
ing multiple data segments that were not marked read-only. 


Attempt was made to load a compressed executable file. The file must be 
decompressed before it can be loaded. 


Dynamic-link library (DLL) file was invalid. One of the DLLs ae to 
run this application was corrupt. 


Application requires Microsoft Windows 32-bit extensions. 


The WinExec function provides an alternative method for executing an applica- 


tion. 


The following example uses the LoadModule function to run an executable file 


named DRAW.EXE: 

struct LOADPARMS { 
WORD segEnv; | /* child environment ¥*/ 
LPSTR IpszCmdLine; /* child command tail */ | 
LPWORD 1pwShow; /* how to show child */ 
LPWORD |lpwReserved; /* must be NULL * / 


ae 


char szMsg[8@]; 

HINSTANCE hinstMod; 

struct LOADPARMS parms; 

WORD awShow[2] = { 2, SW_SHOWMINIMIZED }; 


LoadProc 
parms.segEnv = Q; /* child inherits environment */ 
parms.]pszCmdLine = (LPSTR) ""; = /* no command line * / 
parms.|lpwShow = (LPWORD) awShow; — /* shows child as an icon */ 
parms.1pwReserved = (LPWORD) NULL; /* must be NULL * / 
hinstMod = LoadModule("draw.exe", &parms); 
if ((UINT) hinstMod < 32) { 
sprintf(szMsg, "LoadModule failed; error code = %d", 
hinstMod); . 

MessageBox(hwnd, szMsg, "Error", MB_ICONSTOP); 

} : 7 

else { 
sprintf(szMsg, “"LoadModule returned 4d", hinstMod); 
MessageBox(hwnd, szMsg, "", MB_OK); 

See Also FreeModule, GetModuleFileName, GetSystemDirectory, GetWin- | 


dowsDirectory, ShowWindow, WinExec 


LoadProc | 


HGLOBAL CALLBACK LoadProc(hglbMem, hinst, hrsrcResInfo) 


HGLOBAL hglbMem; _/* handle of object containing resource ef 
HINSTANCE hinst;  —s/* handle of applicationinstance  _ */ 
HRSRC Csr Resinio /* handle of aresource _ a */ 
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The LoadProc function is an application- -defined callback Grictiol that receives 


information about a resource to be locked and can process that information as 


needed. 


Parameters hglbMem | 


Identifies a memory object that contains a resource. This parameter is NULL if 


the resource has not yet been loaded. 
_hinst | 


Identifies the instance of the module whose executable file contains the re- 


source. 
hrsrcResInfo 


Identifies the resource. The resource must have been created by using the 


FindResource function. 


Return Value The return vale isa global memory handle for memory that was allocated using © 


_ the GMEM_DDESHARE Hag 1 in the GlobalAlloc function. 
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Comments 


See Also 


LoadResource 


If an attempt to lock the memory object identified by the hg/bMem parameter fails, 
this means the resource has been discarded and must be reloaded. 


LoadProc is a placeholder for the application-defined function name. The actual 


name must be exported by including it in an EXPORTS statement in the applica- 
tion’s module-definition file. 


FindResource, GlobalAlloc, SetResourceHandler 


HGLOBAL LoadResource(hinst, hrsrc) 


HINSTANCE hinst; 
HRSRC hrsrc; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of file containing resource */ 
/* handle of resource a 


The LoadResource function loads the specified resource in global memory. 


hinst — | | 
Identifies an instance of the module whose executable file contains the resource 
to be loaded. 


hrsrc 
Identifies the resource to be loaded. This handle must have been created by 
using the FindResource function. | 


The return value is the instance handle of the global memory object containing the ~ 
data associated with the resource. It is NULL if no such resource exists. 


When finished with a resource, an application should free the global memory as- 
sociated with it by using the FreeResource function. 


If the specified resource has been loaded, this function simply increments the refer- 
ence count for the resource. 


The resource is not loaded until the LockResource function is called to translate 
the handle returned by LoadResource into a far pointer to the resource data. 


Find Resource RraaRacnanreroa TFT ack Daacaws 
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LoadString [2x | 


int LoadString(hinst, idResource, IpszBuffer, cbBuffer) 


HINSTANCE hinst; /* handle of module containing string resource **/ 
UINT idResource; ——sSs/* resource identifier */ 
LPSTR /[pszBuffer; /* address of buffer for resource */ 
int cbBuffer; /* size of buffer | sa 


The LoadString function loads the specified string resource. 


Parameters hinst 
: Identifies an instance of the module whose exeeuiible file contains the string re- 


source to be loaded. 


idResource 
Specifies the integer identifier of the string to be loaded. 


lpszBuffer 
Points to the buffer that will receive the null- terminated string. 


cbBuffer 
Specifies the buffer size, in bytes. The buffer should be large enough for the 
string and its terminating null character. The string is truncated if itis longer 
than the number of bytes specified. 


Return Value The return value specifies the dimaber of bytes copied into the buffer, if the func- 
tion is successful. It is zero if the string resource does not exist. 


LocalAlloc a rex] 


HLOCAL LocalAlloc(fuAllocFlags, fuAlloc) 


UINT fuAllocFlags; —_/* allocation attributes atl 

UINT fuAlloc; /* number of bytes to allocate i | 
The LocalAlloc function allocates the specified number of bytes from the local — 
heap. 

Parameters  -fuAllocFlags 


Specifies how to allocate memory. This paranietet can be a combination of the 
following values: 
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Return Value 


| Comments 


See Also 


Value 
LHND 


~ LMEM_DISCARDABLE 


LMEM_ FIXED 
LMEM_ MOVEABLE 


LMEM_NOCOMPACT 


Meaning 

Combines the LMEM_MOVEABLE and 
LMEM_ZEROINIT flags. 

Allocates discardable memory. 


Allocates fixed memory. The LMEM_FIXED and 
LMEM_MOVEABLE flags cannot be combined. 


Allocates movable memory. The LMEM_FIXED and 
LMEM_MOVEABLE flags cannot be combined. 


Does not compact or discard memory to satisfy the al- 


location request. 


LMEM_NODISCARD Does not discard memory to satisfy the allocation re- 


quest. 


LMEM_ZEROINIT Initializes memory contents to zero. 


LPTR Combines the LMEM_FIXED and 
LMEM_ZEROINIT flags. 
NONZEROLHND Same as the LMEM_MOVEABLE flag. 
NONZEROLPTR Same as the LMEM_FIXED flag. 
fuAlloc 


Specifies the number of bytes to be allocated. 


The return value is the instance handle of the newly allocated local memory ob- 
ject, if the function is successful. Otherwise, itis NULL. _ 


If LocalAlloc allocates movable memory, the return value is a local handle of the 
memory. To access the memory, an application must use the LocalLock function 
to convert the handle to a pointer. 


If LocalAlloc allocates fixed memory, the return value is a pointer to the memory. 
To access the memory, an application can simply cast the return value to a pointer. 


Fixed memory will be slightly faster than movable memory. If memory will be al- 
located and freed without an intervening local allocation or reallocation, then the 
memory should be allocated as fixed. 


Tf this Fonction is successful, it allocates at least the amount requested. If the 


amount allocated is greater than the amount requested, the application can use the 
entire amount. To determine the size of a local Oy object, an application can 
use the LocalSize function. | 


To free a local memory object, an application should use the LocalFree function. 


To change the size or attributes of an allocated memory object, an application can 
use the LocalReAlloc function. 


LocalFree, LocalLock, LocalReAlloc, LocalSize, LocalUnlock 
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LocalCompact [2x] 


UINT LocalCompact(uMinFree) 
UINT uMinFree; /* amount of memory requested a 


The LocalCompact function rearranges the local heap so that the specified 
amount of memory is free. 


Parameters uMinFree 
| Specifies the number of contiguous free bytes requested. If this parameter is 
zero, the function does not compact memory, but the return value is valid. 


Return Value The return value specifies the number of bytes in the largest free local memory ob- 
ject. If the uMinFree parameter is zero, the return value specifies the number of ' 
bytes in the largest free object that Windows can generate if it removes all discard- 
able objects. 


Comments — The function first checks the local heap for the specified number of contiguous 
: free bytes. If the bytes do not exist, the function compacts local memory by 
moving all unlocked, movable objects into high memory. If this does not generate 
the requested amount of space, the function discards movable and discardable ob- 
jects that are not locked, until the peers amount of space is generated (if 
possible). 


See Also | LocalAlloc, LocalLock 


LocalFirst i raat] 


#include <toolhelp.h> 


BOOL LocalFirst(iple, hglbHeap) 
LOCALENTRY FAR* Iple; /* address of LOCALENTRY structure */ 
HGLOBAL /hglbHeap; /* handle of local heap sy | 


The LocalFirst function fills the specified structure with information that de- 
scribes the first object on the local heap. 


Parameters ple 
Points to a LOCALENTRY structure that will receive information about the 
local memory object. The LOCALENTRY structure has the following form: 


990 LocalFlags 


#Hinclude <toolhelp.h> 


typedef struct tagLOCALENTRY { /* le */ 
DWORD dwSize; 
HLOCAL hHandle; 
WORD wAddress; 
WORD wSize; 
WORD wFlags; 
WORD wcLock; 
WORD wlype; 
WORD hHeap; 
WORD wHeaplType; 
WORD wNext; 

} LOCALENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hglbHeap | 
Identifies the local heap. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The LocalFirst function can be used to begin a local heap walk. An application 
can examine subsequent objects on the local heap by using the LocalNext func- 
tion. | ; 


Before calling LocalFirst, an application must initialize the LOCALENTRY 
structure and specify its size, in bytes, in the dwSize member. 


See Also LocalInfo, LocalNext 


LocalFlags [ax] 


UINT LocalFlags(hloc) oy 
HLOCAL hiloc; —_—/* handle of local memory object */ 


The LocalFlags function retrieves information about the given local memory ob- 
ject. | | 


Parameters hloc 
: s Identifies the local memory object. 
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Return Value The low-order byte of the return value contains the lock count of the object; the 
high-order byte contains either LMEM_DISCARDABLE (object has been marked 
as discardable) or LMEM_DISCARDED (object has been discarded). 


Comments To retrieve the lock count from the return value, use the LMEM_LOCKCOUNT 
mask. | 
See Also LocalAlloc, LocalLock, LocalReAlloc, LocalUnlock 


LocalFree Pax] 


HLOCAL LocalFree(hiloc) 
HLOCAL hloc; /* handle of local memory object oF 


The LocalFree function frees the given local memory object (if the object is not 
locked) and invalidates its handle. | 


Parameters hloc 
| Identifies the local memory object to be freed. — 


Return Value The return value is NULL if the function is successful. Otherwise, it is equal to the 
hloc parameter. : 
Comments An application cannot use the LocalFree function to free a locked memory ob- 


ject—that is, a memory object with a lock count greater than zero. 


After freeing the handle of the memory object, an application cannot use the 
handle again. An attempt to free the same memory object more than once can 
cause Windows to terminate abnormally. 


See Also LocalFlags, LocalLock 


LocalHandle ra a 
HLOCAL LocalHandle(pyMem) | | | 
void NEAR* pvMem; /* address of local memory object */ 


The LocalHandle function retrieves the handle of the specified local memory 
object. 7 


592 Localinfo 


Parameters pvMem 
Specifies the address of the local memory object. 


Return Value The return value is the handle of the specified local memory object if the function 
is successful. It is NULL if the specified address has no handle. 


See Also LocalAlloc 


Locallnfo EXE 


#include <toolhelp.h> 
BOOL LocalInfo(/pli, hglbHeap) 


LOCALINFO FAR® Jpili; /* address of LOCALINFO structure +] 

HGLOBAL hglbHeap; /* handle of local heap */ 
The LocalInfo function fills the specified structure with information that describes 
the local heap. 

Parameters [pli 


Points to a LOCALINFO structure that will receive information about the 
local heap. The LOCALINFO structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagLOCALINFO { /* li */ 
DWORD dwSize; 
WORD wcItems; 

} LOCALINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. . 


hglbHeap 
Identifies the local heap to be described. 


Return Value The return value is nonzero if the function is successful. Otherwise, it iS zero. 


Comments The information in the LOCALINFO structure can be used to determine how 
: -much memory to allocate for a local heap walk. 


Before calling LocalInfo, an application must initialize the LOCALINFO struc- 
ture and specify its size, in bytes, in the dwSize member. 
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See Also LocalFirst, LocalNext 


Localinit Sarre 


BOOL LocalInit(uSegment, uStartdddr, uEndAddr) 


UINT uSegment; /* segment to contain local heap */ 
UINT uStartAddr; /* starting address for heap sf | 
UINT uEndAddr; /* ending address for heap a 


The LocalInit function initializes a local heap in the specified segment. 


Parameters | uSegment 
Identifies the segment that is to contain the local heap. 


uStartAddr — | 
Specifies the starting address of the local heap within the segment. 


uEndAddr 
Specifies the ending address of the local heap within the segment. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The first 16 bytes of the segment containing a local heap must be reserved for use 
by the system. 


See Also GlobalLock, LocalAlloc, LocalReAlloc 


LocalLock 3 


void NEAR* LocalLock(hloc) 
HLOCAL hloc; /* handle of local memory object i 


The LocalLock function retrieves a pointer to the given local memory object. — 
LocalLock increments (increases by one) the lock count of movable objects and 
locks the memory. | | 


Parameters hloc 
Identifies the local memory object to be locked. 
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Return Value 


Comments 


See Also 


LocalNext 


The return value points to the first byte of memory in the local object, if the func- 
tion is successful. It is NULL if the object has been discarded or an error occurs. 


Each time an application calls LocalLock for an object, it must eventually call 
LocalUnlock for the object. 


This function will return NULL if an application attempts to lock a memory object 
with a size of 0 bytes. 


~ The LocalUnlock function decrements (decreases by one) the lock count for the | 


object if LocalLock incremented the count. Other functions can also affect the 
lock count of a memory object. 


Locked memory will not be moved or discarded unless the memory object is 
reallocated by the LocalReAlloc function. The object remains locked in memory 
until its lock count is decreased to zero. 


Discarded objects always have a lock count of zero. 


LocalFlags, LocalReAlloc, LocalUnlock 


#include <toolhelp.h> 


BOOL LocalNext(/ple) | | 
LOCALENTRY FAR? Iple; /* address of LOCALENTRY structure */ 


Parameters 


The LocalNext function fills the specified structure with information that de- 
scribes the next object on the local heap. 


lple 
Points to a LOCALENTRY structure that will receive information about the 
local memory object. The LOCALENTRY structure has the following form: 


include se oginel he h> 


tynedef struct taglLOCALENTRY { /* le #*/ 
DWORD dwSize; | 
HLOCAL hHandle; 
WORD wAddress; 
WORD  ~=wSize; 
WORD ~=wFilags; 
WORD wcLock; 
WORD wlype; 
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WORD hHeap; 
~ WORD wHeapType; 
WORD wNext; 
} LOCALENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value | The return value is nonzero if the function is successful. Otherwise, it is zero. 

Comments The LocalNext function can be used to continue a local heap walk started by the 
= LocalFirst function. 

See Also - LocalFirst, LocalInfo 


LocalReAlloc i Os Or 


HLOCAL LocalReAlloc(hloc, fuNewSize, fuFlags) 

HLOCAL hloc; /* handle of local memory object i | 

UINT fuNewSize; /* new size of object ee | 

UINT fuFlags; /* new allocation attributes hia 2 


The LocalReAlloc function changes the size or attributes of the given local 
memory object. 


Parameters hloc 
| | Identifies the local memory object to be reallocated. 


fuNewSize 
Specifies the new size of the iscal memory object. 


fuF lags 
Specifies how to reallocate the local memory object: If this parameter includes | 
the LMEM_MODIFY and LMEM_DISCARDABLE flags, LocalReAlloc ig- 
nores the fuNewSize parameter. The fuFlags parameter can be a combination of 
the following values. vae 3 


Value Meaning 


LMEM_DISCARDABLE ‘Causes a previously movable object to become 
ade . discardable. This flag can be used only with 
LMEM_MODIFY. | 


LMEM_MODIFY | Modifies the object’ s memory flags. This flag can be 
: oe used only with LMEM_DISCARDABLE. 
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Return Value 


Comments 


See Also 


LocalShrink 


Value Meaning 


LMEM_MOVEABLE If fuNewSize is zero, this flag causes a previously 
fixed object to be freed or a previously movable 
object to be discarded (if the object’s lock 
count is zero). This flag cannot be used with 
LMEM_MODIFY. 

If fuNewSize is nonzero and the object identified by 
the hloc parameter is fixed, this flag allows the reallo- 
cated object to be moved to a new fixed location. 

LMEM_NOCOMPACT Prevents memory from being compacted or discarded 
to satisfy the allocation request. This flag cannot be 
used with LMEM_MODIFY. 

LMEM_ZEROINIT If the object is growing, this flag causes the addi- 
tional memory contents to be initialized to zero. This 
flag cannot be used with LMEM_MODIFY. 


The return value is the handle of the reallocated local memory object, if the func- 
tion is successful. Otherwise, it is NULL. 


If LocalReAlloc reallocates a movable object, the return value is a local handle of 
the memory. To access the memory, an application must use the LocalLock func- 
tion to convert the handle to a pointer. 


If LocalReAlloc reallocates a fixed object, the return value is a pointer to the 
memory. To access the memory, an application can simply cast the return value to 
a pointer. 


To free a local memory object, an application should use the LocalFree function. 


LocalAlloc, LocalDiscard, LocalFree, LocalLock 


UINT LocalShrink(hloc, cbNewSize) 


HLOCAL hloc; 
UINT chNewSize; 


Parameters — 


/* segment containing local heap ] 
/* new size of local heap */ 


The LocalShrink function shrinks the local heap in the given segment. 


hloc | 
Identifies the segment that contains the local heap. If this parameter is zero, the 
function shrinks the heap in the current data segment. 


Return Value 


Comments 
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cbNewSize 
Specifies the 1 new size, in bytes, of the local heap. 


The return value eens the new size of the local heap if the function is suc- 
cessful. 


Windows will not shrink the portion of the data segment that contains the stack 
and the static variables. 
Use the GlobalSize function to determine the new size of the data segment. 
See Also GlobalSize 
LocalSize Ea 
UINT LocalSize(hloc) 
HLOCAL hloc; /* handle of local memory object sf ee 
| The LocalSize function returns the current size, in bytes, of the given local 
memory object. 
Parameters hloc 


Return Value 


Comments 


See Also 


Identifies the local memory object. 


The return value specifies the size, in bytes, of the memory object, if the function © 
is successful. It is zero if the specified handle is invalid or if the object has been 
discarded. 


The size of a memory object sometimes is larger than the size requested when the 


memory was allocated. 


To verify that the memory object has not been discarded, an application should | 
call the LocalFlags function prior to calling the LocalSize function. If the _ 
memory object has been discarded, the return value for LocalSize is meaningless. 


~ LocalAlloe, LocalFlags 


098 LocalUnlock 


LocalUnlock [2x | 


BOOL LocalUnlock(hloc) 
HLOCAL hiloc; /* handle of local memory object sa 


The LocalUnlock function unlocks the given local memory object. This function 
has no effect on fixed memory. 


Parameters hloc 
Identifies the local memory object to be unlocked. 


Return Value The return value is zero if the function is successful. Otherwise, it is nonzero. 


Comments With discardable memory, this function decrements (decreases by one) the ob- 
ject’s lock count. The object is completely unlocked, and subject to discarding, if 
the lock count is decreased to zero. 


See Also LocalLock 


Lockinput Ba] 


BOOL LockInput(Reserved, hwndInput, fLock) 


HANDLE hReserved; /* reserved, must be NULL */ 
HWND hwndInput; /* handle of window to receive all input */ 


BOOL /fLock; /* the lock/unlock flag */ 


The LockInput function locks input to all tasks except the current one, if the 
Lock parameter is TRUE. The given window is made system modal; that is, it will 
receive all input. If fLock is FALSE, ei ta unlocks input and restores the sys- 
tem to its unlocked state. 


Parameters _ hReserved 
_ This parameter is reserved and must be NULL. 
hwndInput 


Identifies the window that is to receive all input. This window must be in the 
current task. If fLock is FALSE, this parameter should be NULL. 


fLock 


Indicates whether to lock or unlock input. A value of TRUE locks input; a 
value of FALSE unlocks input. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
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Comments Before entering hard mode, a Windows-based debugger calls LockInput, specify- 
| ing TRUE for the fLock parameter. This action saves the current global state. To 
exit hard mode, the debugger calls LockInput, specifying FALSE for fLock. This 
restores the global state to the conditions that existed when the debugger entered 
hard mode. A debugger must restore the global state before exiting. Calls to Lock- 
Input cannot be nested. 


See Also Directed Yield 


LockResource x] 


void FAR* LockResource(hglb) | 
HGLOBAL heglb; /* handle of resource ia 


; The LockResource function locks the given resource. The resource is locked in 
memory and its reference count is incremented (increased Dy one). ne locked re- 
source is not subject to discarding. 


Parameters § —S gl 
a Identifies the resource to be locked. This handle must have been created by 
| ene the LoadResource function. ? 


Return Value = Thereturn value pont to the first byte of the loaded resource if the function i 1S 
: | successful. Otherwise, it is N ULL. | 


Comments The resource remains locked in memory until its reference count is s decreased to. 
zero by calls to the FreeResource function. 


If the resource identified by the hglb parameter has been discarded, the resource- 
handler function (if any) associated with the resource is called before the Lock- 
Resource function returns. The resource-handler function can recalculate and 
reload the resource if necessary. After the resource-handler function returns, 
LockResource makes another attempt to lock the resource and returns with the 
result. ne 


Using the handle returned by the FindResource function for the hglb parameter 
causes an error. 


Use the UnlockResource macro to unlock a resource that was locked by HOEK 
Resource. 


See Also FindResource, FreeResource, SetResourceHandler 
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LockSegment ery 


HGLOBAL LockSegment(uSegment) 


UINT uSegment; 


a” 


Parameters 


Return Value 


Comments 


See Also 


/* segment to lock */ 


The LockSegment function locks the specified discardable segment. The segment 
is locked into memory at the given address and its lock count is incremented 
(increased by one). 


uSegment 
Specifies the segment address of the segment to be locked. If this parameter 
is —1, the LockSegment function locks the current data segment. 


The return value specifies the data segment if the function is successful. It is 
NULL if the segment has been discarded or an error occurs. 


Locked memory is not subject to discarding except when a portion of the segment 
is being reallocated by the GlobalReAlloc function. The segment remains locked 
in memory until its lock count is decreased to zero by the UnlockSegment func- 
tion. ° | 


Each time an application calls LockSegment for a segment, it must eventually call 
UnlockSegment for the segment. The UnlockSegment function decrements the 
lock count for the segment. Other functions also can affect the lock count of a 
memory object. For a list of these functions, see the description of the Global- 
Flags function. | 


GlobalFlags, GlobalReAlloc, LockData, UnlockSegment 


LockWindowUpdate 


BOOL LockWindowUpdate(hwndLock) 


HWND hwndLock; 


Parameters 


/* handle of window 2 


The Lock WindowUpdate function disables or reenables drawing in the given 
window. A locked window cannot he moved. Only one window can be locked at a 
time. 


hwndLock : | : 
Identifies the window in which drawing will be disabled. If this parameter is 
NULL, drawing in the locked window is enabled. 
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Return Value — The return value is nonzero if the function is successful. It is zero if a failure oc- 
curs or if the Lock WindowUpdate function has been used to lock another win- 
dow. | 


Comments If an application with a locked window (or any locked child windows) calls the 
| GetDC, GetDCEx, or BeginPaint function, the called function returns a device 
context whose visible region is empty. This will occur until the application un- 
locks the window by calling LockWindowUpdate, specifying a value of NULL 
for hwndLock. 


While window updates are locked, the system keeps track of the bounding 
rectangle of any drawing operations to device contexts associated with a locked 
window. When drawing is reenabled, this bounding rectangle is invalidated in the 
locked window and its child windows to force an eventual WM_PAINT message 
to update the screen. If no drawing has occurred while the window updates were 
locked, no area is invalidated. 


The Lock WindowUpdate function does not make the given window invisible and 
does not clear the WS _VISIBLE style bit. 


LOQHIOR os ek Sa 


void LogError(uErr, lpvinfo) | z. 
UINT uErr; /*errortype | */ 
void FAR* IpvInfo; /* address of error information sa 


The LogError function identifies the most recent system error. An application’ s 
interrupt callback function typically calls LogError to return error information to 
the user. | 


Parameters © uErr | | 
| | Specifies the type of error that occurred. The /pv/nfo parameter may point to 
more information about the error, depending on the value of uErr. This parame- | 
ter may be one or more of the following values: 


Value | Meaning 
ERR_ALLOCRES AllocResource failed. 
ERR _ BADINDEX Bad index to GetClassLong, GetClass Word, 


GetWindowLong, GetWindow Word, Set- 
ClassLong, SetClassWord, eee 
or SetWindowWord. | | 


_ ERR_BYTE | Invalid 8-bit parameter. 
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LogError 


Return Value 


Value 


ERR_CREATEDC 
ERR_CREATEDLG 
ERR_CREATEDLG2 


ERR_CREATEMENU 
ERR_CREATEMETA 
ERR_CREATEWND 


ERR_DCBUSY 
ERR _ DELOBJSELECTED 


ERR_DWORD 
ERR_GALLOC 
ERR_GLOCK 
ERR_GREALLOC 
ERR_LALLOC 
ERR_LLOCK 
ERR_LOADMENU 
ERR_LOADMODULE 
ERR_LOADSTR 
ERR_LOCKRES 
ERR_LREALLOC 
ERR_NESTEDBEGINPAINT 
ERR_REGISTERCLASS 


ERR_SELBITMAP_ 
ERR_SIZE_MASK 


ERR_STRUCEXTRA 
ERR_WARNING 
ERR_WORD 


lpvInfo 


Meaning 
CreateCompatibleDC, CreateDC, or CreateIC 
failed. 


Could not create dialog box because LoadMenu 
failed. 


Could not create dialog box because Create- 
Window failed. 


Could not create menu. 
CreateMetaFile failed. 


Could not create window because the class was 
not found. 


Device context (DC) cache is full. 


Program is trying to delete a bitmap that is 
selected into the DC. 


Invalid 32-bit parameter. 
GlobalAlloc failed. 
GlobalLock failed. 
GlobalReAlloc failed. 
LocalAlloc failed. 
LocalLock failed. 
LoadMenu failed. 
LoadModule failed. 
LoadString failed. 
LockResource failed. 
LocalReAlloc failed. 
Program contains nested BeginPaint calls. 


RegisterClass failed because the class is already 
registered. 


Program is trying to select a bitmap that is al- 


ready selected. 


Identifies which 2 bits of uErr specify the size of 
the invalid parameter. 


Program is using unallocated space. 
A non-fatal error occurred. 
Invalid 16-bit parameter. 


Points to more information about the error. The value of [pv/nfo depends on the 
value of uwErr. If the value of (uErr & ERR_SIZE_MASK) is 0, lpvInfo is unde- 
fined. Currently, no uErr code has defined meanings for lpvInfo. 


This function does not return a value. 
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Comments — The errors identified by LogError may be trapped by the callback function that 
_ NotifyRegister installs. 


Error values whose low 12 bits are less than Ox07FF are reserved for use by Win- 
dows. 


See Also LogParamError, NotifyRegister 


LogParamError EXE 


void LogParamError(uErr, [pfn, lpvParam) 


UINT uErr; /* error type **/ 
FARPROC Ipjn; /* address where error occurred */ 
void FAR* [pvParam; /* address of more error information | 


The LogParamError function identifies the most recent parameter validation 
error. An application’s interrupt callback function typically calls LogParamError 
to return information about an invalid parameter to the user. 


Parameters uErr 

| Specifies the type of parameter validation error that occurred. The pvParam pa- 
rameter may point to more information about the error, depending on the value 
of uErr. This parameter may be one or more of the following values: 


Value. Meaning 

ERR_BAD_ATOM Invalid atom. 

ERR_BAD_CID | Invalid communications identifier (CID). 

ERR BAD COORDS Invalid x,y coordinates. 

ERR_BAD_DFLAGS Invalid 32-bit flags. 

ERR BAD DINDEX Invalid 32-bit index or index out-of-range. 

ERR_BAD_DVALUE Invalid 32-bit signed or unsigned value. 

ERR_BAD_FLAGS | Invalid bit flags. | 

ERR_BAD FUNC PTR Invalid function pointer. 

ERR_BAD_GDI_OBJECT Invalid graphics device interface (GDI) 
object. 

ERR_BAD_GLOBAL_HANDLE __ Invalid global handle. 

ERR_BAD HANDLE Invalid generic handle. 

ERR_BAD_HBITMAP Invalid bitmap handle. 

ERR_BAD_HBRUSH Invalid brush handle. 


ERR BAD HCURSOR Invalid cursor handle. 
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LogParamError 


Value 

ERR BAD HDC 
ERR BAD HDRVR 
ERR BAD HDWP 


~ ERR_BAD_HFILE 


ERR_BAD_HFONT 
ERR_BAD_HICON 
ERR_BAD_HINSTANCE 


ERR BAD HMENU 


ERR_BAD_HMETAFILE 
ERR_BAD_HMODULE 
ERR_BAD_HPALETTE 
ERR_BAD_HPEN 
ERR_BAD_HRGN 
ERR_BAD_HWND 
ERR_BAD_INDEX 
ERR_BAD_LOCAL_HANDLE 
ERR_BAD_ PTR 
ERR_BAD_SELECTOR 
ERR_BAD_STRING_ PTR 
ERR_BAD_VALUE 
ERR_BYTE 

ERR_DWORD 

ERR_PARAM 


ERR_SIZE_MASK 


ERR_WARNING 


ERR_WORD 


lpfn 


Snecifies the address at which the parameter error accurred. This value is 


NI ULL if the address 1 is unknown. 


IpvParam 
Points to more iniformatioi about the error. The value of lpvParam depends on 
the value of wErr. If the value of (uErr & ERR_SIZE_MASK) is 0, IpvParam 
is undefined. Currently, no uErr code has defined meanings for [pvParam. _ 


Meaning 


Invalid device context (DC) handle. 
Invalid driver handle. 


Invalid handle of a window-position 
structure. 


Invalid file handle. 

Invalid font handle. 

Invalid icon handle. 

Invalid instance handle. 

Invalid menu handle. 

Invalid metafile handle. 

Invalid module handle. 

Invalid palette handle. 

Invalid pen handle. 

Invalid region handle. 

Invalid window handle. 

Invalid index or index out-of-range. 
Invalid local handle. 

Invalid pointer. 

Invalid selector. 

Invalid zero-terminated string pointer. 
Invalid 16-bit signed or unsigned value. 


~ Invalid 8-bit parameter. 


Invalid 32-bit parameter. 


A parameter validation error occurred. This 
flag is always set. 

Identifies which 2 bits of uErr specify the 
size of the invalid parameter. 


An invalid parameter was detected, but the 
error is not serious enough to cause the func- 
tion to fail. The invalid parameter is reported, 
but the call runs as usual. 


Invalid 16-bit parameter. 


-— ~~ we Se wre 


Return Value 


Comments 


See Also 


_lopen 
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This function does not return a value. 


The errors identified by LogParamError may be trapped by the callback function 
that NotifyRegister installs. 


Error values whose low 12 bits are less than OxO7FF are reserved for use by Win- 
dows. 


The size of the value passed in /pvParam is determined by the values of the bits 
selected by ERR_SIZE_MASK, as follows: 


switch (err & ERR SIZE_MASK) 


{ 

case ERR_BYTE: /* 8-bit invalid parameter */ 
b = LOBYTE(param); 
break; 

case ERR_WORD: /* 16-bit invalid parameter */ 
w = LOWORD(param) ; 
break; 

case ERR_DWORD: /* 32-bit invalid parameter */ 
1 = (DWORD)param; — 
break: | 

default: _/* invalid parameter value is unknown */ 
break; : 

} 


LogError, NotifyRegister 


_ Ex | 


HFILE _lopen(IpszF ilename, fnOpenMode) 
LPCSTR [pszFilename; /* address of file to open sa 


int fnOpenMode; 


Parameters 


/* file access */ 


The _lopen function opens an existing file and sets the file pointer to the begin- 
ning of the file. | 


lpszFilename | 
Points to a null-terminated string that names the file to be opened. The string 
must consist of characters from the Windows character set. 
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Return Value 


Example 


JnOpenMode 
Specifies the modes in which to open the file. This parameter consists of one 
access mode and an optional share mode. 


Value Access mode 

READ — Opens the file for reading only. 

READ_WRITE Opens the file for reading and writing. 

WRITE Opens the file for writing only. 

Value Share mode (optional) | 
OF_SHARE COMPAT Opens the file in compatibility mode, allowing 


any process on a given machine to open the file 
any number of times. If the file has been opened 
by using any of the other sharing modes, _ lopen 
fails. 


OF_SHARE_ DENY_NONE Opens the file without denying other programs 
read or write access to the file. If the file has been 
opened in compatibility mode by any other pro- 
gram, _lopen fails. 

OF_SHARE DENY_READ Opens the file and denies other programs read 
access to the file. If the file has been opened in 
compatibility mode or for read access by any 
other program, —lopen fails. 

OF_ SHARE DENY_WRITE Opens the file and denies other programs write 
access to the file. If the file has been opened in 
compatibility mode or for write access by any 
other program, —lopen fails. 

OF_SHARE_EXCLUSIVE Opens the file in exclusive mode, denying other 

7 programs both read and write access to the file. If 
the file has been opened in any other mode for 
_ read or write access, even by the current program, 
_lopen fails. 


The return value is a file handle if the function i is successful. Otherwise, it is 
HFILE_ERROR. 


The following example uses the _lopen function to open an input file: 


HFILE hfReadFile; 


/* open the input file (read only). */ 


hfReadFile = _lopen("testfile", READ); 


if (hfReadFile == HFILE_ERROR) { 
ErrorHandler(); 
} 
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See Also OpenFile 


LPtoDP (2x | 


BOOL LPtoDP(hdc, lppt, cPoints) 


HDC hdc; /* handle of device context */ 
POINT FAR* Ippt; /* address of array with points */ 
int cPoints; _/* number of points in array a 


The LPtoDP function converts logical coordinates (points) into device coordinates. 


Parameters hdc 
| Identifies the device context. 
lppt : 
Points to an array of POINT structures. The coordinates in each structure are 
mapped to the device coordinates of the current device context. The POINT 
structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


cPoints 
Specifies the number of points in the array. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The conversion depends on the current mapping mode and the settings of the 
origins and extents of the device’s window and viewport. 


The x- and y-coordinates of points are 2-byte signed integers in the range —32,768 
through 32,767. In cases where the mapping mode would result in values larger 
than these limits, the system sets the values to —32,768 and 32,767, respectively. 


Example The following example sets the mapping mode to MM_LOENGLISH and then 
calls the LPtoDP function to convert the coordinates of a rectangle into device 
coordinates: 
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See Also 


_ fread 


RECT re; 
SetMapMode(hdc, MM _LOENGLISH); 


SetRect(&rc, 100, -100, 200, -200); 
LPtoDP(hdc, (LPPOINT) &rc, 2); 


DPtoLP 


UINT _ Iread(hf, hpvBuffer, cbBuffer) 


HFILE Af; /* file handle */ 
void _huge* hpvBuffer; /* address of buffer for read data */ 
UINT cbBuffer; /* length of data buffer af 
The _ lread function reads data from the specified file. 
Parameters hf 
Identifies the file to be read. 
hpvBuffer 
Points to a buffer that is to receive the data read from the file. 
cbBuffer 


Return Value 


Example 


_ Specifies the number of bytes to be read from the file. This value cannot be 
greater than OXFFFE (65,534). 


The return value indicates the number of bytes that the function read from the file, 
if the function is successful. If the number of bytes read is less than the number 
specified in cbBuffer, the function reached the end of the file (EOF) before reading 
the specified number of bytes. The return value is HFILE_ERROR if the function 
fails. 


The following example uses the _ lread and _ Iwrite functions to copy data from 
one file to another: 


HFILE hfReadFile; 

int cbRead; 

PBYTE nbBuf : 

/* Allocate a buffer for file I/0. */ 


pbBuf = (PBYTE) LocalAlloc(LMEM_FIXED, 2048); 


/* Copy the input file to the temporary file. */ 
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do { 
cbRead = _lread(hfReadFile, pbBuf, 2048); 
_lwrite(hfTempFile, pbBuf, cbRead); 
} while (cbRead != Q); 
/* Free the buffer and close the files. */ 
LocalFree((HLOCAL) pbBuf); 


_lIclose(hfReadFile); 
_Iclose(hfTempFile); 


See Also | _hread, _Iwrite 


Istreat [2.x | 


LPSTR Istreat(/pszString1, IpszString2) 
LPSTR IpszString1; /* address of buffer for concatenated strings sa 
LPCSTR IpszString2; /* address of string to add to string] . wa: 


_ The Istrcat function appends one string to another. 


Parameters lpszString 1 


Points to a byte array containing a null-terminated string. The byte array con- 
taining the string must be large enough to contain both strings. 


[pszString2 | | - 7 
Points to the null-terminated string to be appended to the string specified in the 
IpszString 1] parameter. 
Return Value The return value points to lpszString ] if the function is successful. 
Comments Both strings must be less than 64K in size. 
Example The following example uses the Istrcat function to append a test string to a buffer: 


char szBuf[80] = { “the test string is " }; 


Istrcat(szBuf, lpsz); 
MessageBox(hwnd, szBuf, "Istrcat", MB_OK); 
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Istrcmp 
int Istremp((pszString/, ipszString2) | 


LPCSTR IpszString1; /* address of first string a 
LPCSTR [pszString2;_ —__‘/* address of second string =] 


The Istremp function compares two character strings. The comparison is case- 
sensitive. 


Parameters IpszString 1 
Points to the first null-terminated string to be compared. 


lpszString2 
Points to the second null-terminated Sane to be compared. 


Return Value The return value is less than zero if the string specified in lpszString I is less than 
the string specified in [pszString2, is greater than zero if IpszString/ is te than 
lpszString2, and is zero if the two strings are equal. 


Comments The Istremp function compares two strings by checking the first characters 
against each other, the second characters against each other, and so on, until it 
finds an inequality or reaches the ends of the strings. The function returns the 
difference of the values of the first unequal characters it encounters. For example, 
Istremp determines that “abcz” is greater than “abcdefg”’ and returns the differ- 
ence of “z” and “d’’. 


The language driver for the language selected by the user determines which string 
is greater (or whether the strings are the same). If no language driver is selected, 
Windows uses an internal function. With the Windows United States language 
functions, uppercase characters have lower values than lowercase characters. 


With a double-byte character set (DBCS) version of Windows, this function can 
compare two DBCS strings. 


Both strings must be less than 64K in size. 


See Also Istrempi 


‘Istrcmpi ant 2 ae, 


int Istrempi(/pszString/, lpszString2) 
LPCSTR IpszString 1; /* address of first string i | 
LPCSTR IpszString2; /* address of second string */ 


Parameters 


Return Value 


Comments 


See Also 


Istrepy 
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The Istrempi function compares the two strings. The comparison is not case- 
sensitive. | 


lpszString 1 
Points to the first null-terminated string to be csiineied: 


[pszString2 | 
Points to the second null-terminated string to be compared. 


The return value is less than zero if the string specified in /pszString/ is less than 
the string specified in /pszString2, is greater than zero if IpszString/ is greater than 
IpszString2, and is zero if the two strings are equal. 


The Istrempi function compares two strings by checking the first characters 
against each other, the second characters against each other, and so on, until it 
finds an inequality or reaches the ends of the strings. The function returns the 
difference of the values of the first unequal characters it encounters. For example, 
Istrempi determines that “abcz” is greater than “abcdefg” and returns the differ- 
ence of “z” and “d”’. 


The language driver for the language selected by the user determines which string 
is greater (or whether the strings are the same). If no language driver is see 


Windows uses an internal function. 


With a double-byte character set (DBCS) version of Windows, this function can 


: compare two DBCS strings. | 


~ Both sities must be less than 64K in size. 


eae 


-LPSTR Istrepy([pszString1, lpszString2) 


~ LPSTR IpszString 1; 
LPCSTR [pszString2; 


Parameters 


/* address of buffer ries | 
/* address of string to copy e) 


The Istrepy function copies a string to a buffer. 


lpszString 1 oy oa ae 
Points to a buffer that will receive the contents of the string pointed to by the a 
lpszString2 parameter. The buffer must be large enough to contain the string, in-- 

| cluding the terminating null character. | | 
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lpszString2 
Points to the null-terminated string to be copied. 
Return Value The return value is a pointer to /pszString] if the function is successful. Otherwise, 
itis NULL. _ 
Comments This function can be used to copy a double-byte character set (DBCS) string. 


Both strings must be less than 64K in size. 


See Also Istrlen 


Istrien — Lex] 


int Istrlen(/pszString) 
LPCSTR l[pszString; /* address of string to count + 


The Istrlen function returns the length, in bytes, of the eee string (not includ- 
ing the terminating null character). 


Parameters IpszString 
Points to a null-terminated string. This string must be less than 64K in size. 


Return Value The return value specifies the length, in bytes, of the string pointed to by the 
lpszString parameter. There is no error return. 


See Also Istrepy 


_ Iwrite [ax | 


UINT _Iwrite(hf, hpvBuffer, cbBuffer) 7 
HFILE hf; /* file handle | 


CONS VoIG _nuge™ npvBujjer, /* address of buiier for write data ob 
UINT cbBuffer; 3 | /* size of data ns 


_ The _Iwrite function writes data to the specified file. 
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Parameters hf | 
Identifies the file to be written to. 


hpvBuffer | 7 
Points to a buffer that contains the data to be written to the file. 


cbBuffer 
Specifies the number of bytes to be written to the file. If this parameter is zero, 
the file is expanded or truncated to the current file-pointer position. 


Return Value The return value indicates the number of bytes written to the file, if the function is 
: successful. Otherwise, the return value is HFILE_ERROR. 


Comments The buffer specified by hpvBuffer cannot extend past the end of a segment. 


Example The following example uses the _lread and _Iwrite functions to copy data from 
_ one file to another: 


int cbRead; 
PBYTE pbBuf; 


/* Allocate a buffer for file 1/0. */ 

pbBuf = (PBYTE) LocalAlloc(LMEM_FIXED, 2048); 

/* Copy the input file to the temporary file. */ 
~ edo .f{ en are ea 
cbRead = _lread(hfReadFile, pbBuf, 2048); 
7 _Iwrite(hfTempFile, pbBuf, cbRead); 

} while (cbRead != @);° 
/* Free the buffer and close the files. */. 


~ LocalFree((HLOCAL) pbBuf); 


_lIclose(hfReadFile); 
_Iclose(hfTempFile) ; 


See Also _hwrite, _lread 
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LZClose a EXE 


#include <Izexpand.h> 


void LZClose(h/) 
HFILE hf; /* handle of file to be closed */ 


The LZClose function closes a file that was opened by the LZOpenFile or Open- 
File function. 


Parameters hf 
Identifies the source file. 


Return Value This function does not return a value. 


Comments If the file was compressed by Microsoft File Compression Utility 
(COMPRESS.EXE) and opened by the LZOpenFile function, LZClose 
frees any global heap space that was required to expand the file. 


Example — The following example uses LZ Close to close a file opened by LZOpenFile: 


char szSrc{] = {"readme.txt"}; 

char szDstL] = {"readme.bak"}; 

OFSTRUCT ofStrSrc; | 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile; 

/* Open the source file. */ | 

hfSrcFile = LZOpenFile(szSrc, &ofStrSrc, OF_READ); 

/* Create the destination file. */ 

hfDstFile = LZOpenFile(szDst, &ofStrDest, OF_CREATE); 
|x Copy the source file to the destination file. */ 


LZCopy(hfSrcFile, hfDstFile); 


/* Close the files. */ 


See Also - OpenFile, LZOpenFile 


LZCopy 
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[3.1 | 


#include <lzexpand.h> 


LONG LZCopy(hfSource, hfDest) 


HFILE hfSource; 


HFILE hfDest; 


Parameters 


Return Value — 


Comments 


/* handle of source file a | 
/* handle of destination file */ 


The LZCopy function copies a source file to a destination file. If the source file 
was compressed by Microsoft File Compression Utility (COMPRESS.EXE), this 
function creates a decompressed destination file. If the source file was not com- 
pressed, this function duplicates the original file. 


hfSource 
Identifies the source file. (This handle: is returned by the LZOpenFile function 
when a compressed file is opened.) | 


hfDest 


Identifies the desaaiaon file. 


The return value is the size, in bytes, of the destination file if the function is 


successful. Otherwise, it is an error value that is less than zero and may be one of 


the following: 
Value | ae Meaning | bee 
LZERROR_BADINHANDLE | The handle identifying the source file was not 
a, | valid. — | 
LZERROR_BADOUTHANDLE _ The handle identifying the destination file was 
| = not valid. | 
LZERROR_GLOBALLOC There is insufficient memory for the ree 
buffers. 
LZERROR_GLOBLOCK The handle identifying the internal data structures 
| is invalid. : 
~ LZERROR READ . meen ee The source file format was not valid. 
LZERROR_UNKNOWNALG _ The source file was compressed with an unrecog- 
- _ nized compression algorithm. 
LZERROR_WRITE | There is insufficient space for the output file. 


This function is designed for single -file copy operations. (Use the CopyLZFile 
function for multiple- -file copy operations, ) 


If the function is successful, the file identified by hfDest is a 


If the source or destination file is opened by a C run-time function (rather than the 


_lopen or Openkile function), it must be opened i in banat mode. 
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Example 


See Also 


The following example uses the LZCopy function to copy a file: 


char szSrc[] = {"readme.txt"}; 

char szDst[] = {"readme.bak"}; 

OFSTRUCT ofStrSrc; 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile; 

/* Open the source file. */ 

hfSrcFile = LZOpenFile(szSrc, &ofStrSrc, OF_READ); 
/* Create the destination file. */ 

hfDstFile = LZOpenFile(szDst, &ofStrDest, OF_CREATE); 
/* Copy the source file to the destination file. */ 
LZCopy(hfSrcFile, hfDstFile); 

/* Close the files. */ 


LZClose(hfSrcFile); 


LZClose(hfDstFile); 


CopyL ZFile, _lopen, LZOpenFile, OpenFile 


LZDone 


#include <Izexpand.h> 


void LZDone(void) 


Parameters 
Return Value 


Comments 


Example 


The LZDone function frees buffers that the LZStart function allocated for 
multiple-file copy operations. 


This function has no parameters. 
This function does not return a value. 


Applications that copy multiple files should call LZStart before copying the files 
with the CopyLZFile function. LZStart allocates buffers for the file copy opera- 
tions. 


The following example uses LZDone to free buffers allocated by LZStart: 
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See Also 


LZInit 


ftdefine NUM_FILES 4 


char *szSrcLNUM_FILES] = 

{"readme.txt", "data.txt", "update.txt", “list.txt"}; 
char *szDest~NUM_FILES] = 

{"readme.bak", "“data.bak", “update.bak", “list.bak"}; 
OFSTRUCT ofStrSrc; 
OFSTRUCT ofStrDest; 
HFILE hfSrcFile, hfDstFile; 
int i; 


/* Allocate internal buffers for the CopyLZFile function. */ 


LZStart(); 


_/* Open, copy, and then close the files. */ 


for (i = 0; i < NUM_FILES; i++) { 
hfSrcFile = LZOpenFile(szSrc[Li], &ofStrSrc, OF_READ); 
hfDstFile = LZOpenFile(szDestLi], &ofStrDest, OF_CREATE); 
CopyLZFile(hfSrcFile, hfDstFile); 
LZClose(hfSrcFile); 

 LZClose(hfDstFile); 
} 
LZDone(); /* free the internal buffers */ 


CopyLZFile, LZCopy, LZStart 


#include <lzexpand.h> 


HFILE LZInit(hfSrc) 


HFILE //fSrc; 


Parameters 


Return Value 


/* handle of source file #/ | 


The LZInit function allocates memory for, creates, and initializes the internal data 


structures that are required to Eecompres files. 


hfSre 


Identifies the source file. 


The return value | is the original file aaidle if the function is successful aad the file 
is not compressed. If the function is successful and the file is compressed, the re- 
turn value is a new file handle. If the function fails, the return value is an error 
value that is less than zero and may be one of the following: 7 
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Value Meaning 
LZERROR_BADINHANDLE The handle identifying the source file is invalid. 
LZERROR_GLOBALLOC There is insufficient memory for the required inter- 


Comments 


Example 


nal data structures. This value is returned when an 
application attempts to open more than 16 files. 


LZERROR_GLOBLOCK The handle identifying global memory is invalid. 


(The internal call to the GlobalLock function 
failed.) | | | 
LZERROR_READ The source file format is invalid. 


LZERROR_UNKNOWNALG The file was compressed with an unrecognized com- 
pression algorithm. 


A maximum of 16 compressed files can be open at any given time. 


The following example uses LZInit to initialize the internal structures that are re- 
quired to decompress a file: 


char szSrc[] = {"readme.cmp"}; 

char szFileName[128]; 

OFSTRUCT ofStrSrc; 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile, hfCompFile; 
int cbRead; 


BYTE abBuf[512]; 


/* Open the compressed source file. */ 

hfSrcFile = OpenFile(szSrc, &ofStrSrc, OF_READ); 

/* 

* Initialize internal data structures for the decompression 
* operation. 

* / 

hfCompFile = LZInit(hfSrcFile); 

/* Retrieve the original name for the compressed file. */ 


GetExpandedName(szSrc, szFileName); 


/* Create the destination file using the original name. */ 


OF COEATE) e 


wikbsw st +) 


hfDstFile = |7OnenFile(s7FileNama, kofStrDest 


/* Copy the compressed source file to the destination file. */ 


do { | | | 
if ((cbRead = LZRead(hfCompFile, abBuf, sizeof(abBuf))) > @) 
_lwrite(hfDstFile, abBuf, cbRead); | 
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else { 
. /* handle error condition */ 


} 
} while (cbRead == sizeof(abBuf)); 


/* Close the files. */ 


LZClose(hfSrcFile); 
LZClose(hfDstFile); 


LZOpenFile = [ 3.1 | 


#include <Izexpand.h> 

HFILE LZOpenFile(pszFile, lpof, style) | 
LPCSTR IpszFile; /* address of filename ae 
OFSTRUCT FAR® [pof; /* address of structure for fileinfo ~~ */ 
UINT style; | _ /* action to be taken | */ 


The LZOpenFile function creates, opens, reopens, or deletes the file specified by 
the string to which /pszFile points. 


Parameters lpszFile 
Points to a string that specifies the name of a file. 
_lpof 
Points to the OFSTRUCT structure that is to receive information about the 


file when the file is opened. The structure can be used in subsequent calls to 
LZOpenFile to refer to the open file. 


The szPathName member of this structure contains characters from the 
OEM character set. For more information about the OEM character set, see 
the Microsoft Windows Guide to Programming. 


style 
Specifies the action to be taken. These styles can be combined by using the 
bitwise OR operator: 
Value Meaning 
OF_CANCEL Adds a Cancel button to the OF_PROMPT dialog 


box. Choosing the Cancel button directs LZOpen- 
File to return a file-not-found error message. 


OF_CREATE Directs LZOpenFile to create a new file. If the 
. | _ file already exists, it is truncated to zero length. 
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Value Meaning 
OF_DELETE | Deletes the file. 
OF_EXIST Opens the file, and then closes it. This action is 
_used to test for file existence. 
OF_PARSE Fills the OFSTRUCT structure, but carries out 
no other action. 
OF_PROMPT Displays a dialog box if the requested file does 


not exist. The dialog box informs the user that 
Windows cannot find the file and prompts the 
user to insert the disk containing the file in 


drive A. 

- OF_READ Opens the file for reading only. 
OF_READWRITE Opens the file for reading and writing. 
OF_REOPEN Opens the file using information in the reopen 

buffer. 


OF_SHARE_DENY_NONE Opens the file without denying other programs 
read access or write access to the file. LZOpen- 
File fails if the file has been opened in compati- 
bility mode by any other program. 

OF_SHARE DENY_READ Opens the file and denies other programs read 
access to the file. LZOpenFile fails if the file has 
been opened in compatibility mode or for read 
access by any other program. 

OF_SHARE_DENY_WRITE Opens the file and denies other programs write 
access to the file. LZOpenFile fails if the file has 
been opened in compatibility mode or for write 
access by any other program. | 

OF_SHARE_ EXCLUSIVE Opens the file in exclusive mode, denying other 
programs both read access and write access to the 
file. LZOpenFile fails if the file has been opened 
in any other mode for read access or write access, 
even by the current program. 


OF_WRITE Opens the file for writing only. 


Return Value The return value is a handle identifying the file if the function is successful and the 
value specified by style is not OF_READ. If the file is compressed and opened 
with style set to the OF_READ value, the return value i is a special file handle. If 
the function fails, the return value is —1. 


Comments If style is OF_READ (or OF_READ and any of the OF_SHARE_ flags) and the 
| | | file is compressed, LZOpenFile calls the LZInit function, which performs the re- 
: quired initialization for the decompression operations. 
Example | The following example uses LZOpenFile to open a source file and create a desti- 
nation file into which the source file can be copied: 
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char szSrc[] = {"readme.txt"}: 

char szDst[] = {"readme.bak"}; 

OFSTRUCT ofStrSrc; 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile; 

/* Open the source file. */ 

hfSrcFile = LZOpenFile(szSrc, &ofStrSrc, OF_READ); 
/* Create the destination file. */ 

hfDstFile = LZOpenFile(szDst, &ofStrDest, OF_CREATE); 
/* Copy the source file to the destination file. */ 
LZCopy(hfSrcFile, hfDstFile); 

/* Close the files. */ 


L7Close(hfSrcFile); 
LZClose(hfDstFile); 


See Also | LZInit 


LZRead [8A 
#include <lzexpand.h> 


int LZRead(hf, [pvBuf, cb) 


HFILE hf; /* handle of the file . 
void FAR* IpvBuf; /* address of buffer for file data */ 
int cb; /* number of bytes to read si 


The LZRead function reads into a buffer bytes from a file. 


Parameters hf 
Identifies the source file. 
lpvBuf | 
Points to a buffer that is to receive the bytes read from the file. 


cb 
Specifies the maximum number of bytes to be read. 
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Return Value 


Comments 


Example 


The return value is the actual number of bytes read if the function is successful. 
Otherwise, it is an error value that is less than zero and may be any of the follow- 
ing: 7 | 


Value | Meaning 


LZERROR_BADINHANDLE The handle identifying the source file was invalid. 


LZERROR_BADVALUE The cb parameter specified a negative value. 

LZERROR_GLOBLOCK The handle identifying required initialization data is 
7 invalid. 

LZERROR_READ The format of the source file was invalid. 


LZERROR_UNKNOWNALG The file was compressed with an unrecognized com- 
| pression algorithm. 


If the file is not compressed, LZRead calls the _Iread function, which performs 
the read operation. 


If the file is compressed, LZRead emulates _lread on an expanded image of the 
file and copies the bytes of data into the buffer to which /pvBuf points. 


If the source file was compressed by Microsoft File Compression Utility | 
(COMPRESS.EXE), the LZOpenFile, LZSeek, and LZRead functions can be 
called instead of the OpenFile, _llseek, and _lread functions. 


The following example uses LZRead to copy and decompress a compressed file: 


char szSrc[] = {"readme.cmp"}; 

char szFileName[128]; 

OFSTRUCT ofStrSrc; 

OFSTRUCT ofStrDest; 

HFILE hfSrcFile, hfDstFile, hfCompFile; 
int cbRead; : 


BYTE abBuf[512]; 


/* Open the compressed source file. */ 
hfSrcFile = OpenFile(szSrc, &ofStrSrc, OF_READ); 


/* | 
* Initialize internal data structures for the decompression 
* Operation. ; 

a / 


hfCompFile = LZInit(hfSrcFile); 


/* Retrieve the original name for the compressed file. */ 


GetExpandedName(szSrc, szFileName); 
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/* Create the destination file using the original name. */ 
hfDstFile = LZOpenFile(szFileName, &ofStrDest, OF_CREATE); 
/* Copy the compressed source file to the destination file. */ 
do { 
if ((cbRead = LZRead(hfCompFile, abBuf, sizeof(abBuf))) > @) | 
_Ilwrite(hfDstFile, abBuf, cbRead); 


else { 


. /* handle error condition */ 


a 
} while (cbRead == sizeof(abBuf)); 
/* Close the files. */ 


LZClose(hfSrcFile); 
LZClose(hfDstFile); 


See Also _llseek, _Iread, LZOpenFile, LZRead, LZSeek 


LZSeek | 


#include <Izexpand.h> 

LONG LZSeek(hf, [Offset, nOrigin) 

HFILE hf; /* handle of file */ 
long /Offset; /* number of bytes to move **/ 
int nOrigin; —_—‘/* original position */ 


The LZSeek function moves a file pointer from its original position to a new 
position. | 


Parameters hf 
Identifies the source file. 
lOffset 7 | 
Specifies the number of bytes by which the file pointer should be moved. 
nOrigin ee aie oe 
Specifies the starting position of the pointer. This parameter must be one of the 
following values: 
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Value Meaning | 
0 Move the file pointer /Offset bytes from the beginning of the file. 
1 Move the file pointer /Offset bytes from the current position. 
2 Move the file pointer [Offset bytes from the end of the file. 
Return Value The return value is the offset from the beginning of the file to the new pointer posi- 


tion, if the function is successful. Otherwise, it is an error value that is less than 
zero and may be one of the following: 


Value Meaning 
LZERROR_BADINHANDLE The handle identifying the source file was invalid. 
LZERROR_BADVALUE One of the parameters exceeds the range of valid 
, values. 
LZERROR_GLOBLOCK The handle identifying the initialization data 1 is in- 
valid. 
Comments If the file is not compressed, LZSeek calls the _llseek function and moves the file 


pointer by the specified offset. 


If the file is compressed, LZSeek emulates _ Ilseek on an expanded image of the 
file. 


See Also | _llseek 


-LZStart oo [3.1] 


#include <lzexpand.h> 


int LZStart(void) 
The LZStart function allocates the buffers that the CopyLZFile function uses to 
copy a source file to a destination file. 

Parameters This function has no parameters. 

Return Value | The return value is nonzero if the function is successful. Otherwise, it is 
LZERROR_GLOBALLOC. 

Comments | Applications that copy (or copy and decompress) multiple consecutive files should 


call the LZStart, CopyLZFile, and LZDone functions. Applications that copy a 
single file should call the LZCopy function. 


MakeProcinstance 625 


Example 


See Also 


The following example uses LZStart to allocate buffers used by CopyLZFile: 
#Hdefine NUM_FILES 4 


char *szSrc{NUM_FILES] = 

{"readme.txt", "data.txt", “update.txt", "list.txt"}; 
char *szDest{[NUM_ FILES] = 

{"readme.bak", "data.bak", "update.bak", "list.bak"}; 
OFSTRUCT ofStrSrc; 
OFSTRUCT ofStrDest; 
HFILE hfSrcFile, hfDstFile; 
int i; 


/* Allocate internal buffers for the CopyLZFile function. */ 
LZStart(); 
/* Open, copy, and then close the files. */ 


for (i = @; i < NUM_FILES; i++) { 
— hfSrcFile = LZOpenFile(szSrcli], &ofStrSrc, OF_READ); 
~hfDstFile = LZOpenFile(szDest[i], &ofStrDest, OF_CREATE); 
CopyLZFile(hfSrcFile, hfDstFile); 
LZClose(hfSrcFile); 
LZClose(hfDstFile); 
} 


—LZDone(); /* free the internal buffers */ 


CopyLZFile, LZCopy, LZDone 


MakeProclinstance | 2.x | 


FARPROC MakeProclInstance(/pProc, hinst) 


FARPROC [pProc; 
HINSTANCE hinst; 


Parameters 


/* address of function */ 
/* instance to bind to function */ 


The MakeProcInstance function returns the address of the prolog code for an ex- 
ported function. The prolog code binds an instance data segment to an exported 
function. When the function is called, it has access to variables and data in that in- | 
stance data segment. | | 


lpProc 
Specifies the address of an exported function. 
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hinst 
Identifies the instance associated with the desired ac segment. 


Return Value The return value points to the prolog code for the specified exported function, if 
MakeProclInstance is successful. Otherwise, it is NULL. | 


Comments The MakeProcInstance function is used to retrieve a calling address for a func- 
tion that must be called by Windows, such as an About procedure. This function 
must be used only to access functions from instances of the current module. If the 
address specified in the jpProc parameter identifies a procedure in a dynamic-link 
library, MakeProcInstance returns the same address specified in lpProc. 


After MakeProclInstance has been called for a particular function, all calls to that 
function should be made through the retrieved address. 


The FreeProcInstance function frees the function from the data segment bound to 
it by the MakeProcInstance function. 


MakeProcInstance will create more than one procedure instance. To avoid wast- 
ing memory, an application should not call MakeProcInstance more than once 
using the same function and instance handle. 


See Also FreeProcInstance, GetProcAddress 


MapDialogRect aa] 


void MapDialogRect(hwndDlg, Iprc) ’ 
HWND hwnadDie; /* handle of dialog box | 
RECT FAR* Ipic; /* address of structure with rectangle */ 


The MapDialogRect function converts (maps) the specified dialog box units to 
screen units (pixels). | 


Parameters hwndDig 
| | Identifies a dialog box. This dialog box must have been created by using the 
CreateDialog or DialogBox function. | : 


ipre | 
Points to a RECT structure that contains the dialog box coordinates to be con- 
verted. The RECT structure has the following form: = 
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typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value This function does not return a value. 


Comments The MapDialogRect function converts the dialog box units of a rectangle to 
screen units. Dialog box units are defined in terms of the current dialog base unit, 
which is derived from the average width and height of characters in the font used 
_ for dialog box text. Typically, dialog boxes use the System font, but an application 
can specify a different font pd using the DS_SETFONT style in the resource- | 
definition file. 


One horizontal unit is one-fourth of the dialog box base width unit, and one verti- 
cal unit is one-eighth of the dialog box base height unit. The eee 
function retrieves the dialog box base units in pixels. 


See Also CreateDialog, DialogBox, GetDialogBaseUnits 


MapVirtualKey a i 


UINT MapVirtualKey(uKeyCode, fuMapType) 
UINT uKeyCode; /* virtual-key code or scan code */ 
—UINT fuMapType; _‘/* translation to perform */ 


The MapVirtualKey function translates (maps) a virtual-key code into a scan - 
code or ASCII value, or it translates a scan code into a virtual-key code. 


Parameters _ uKeyCode 
Specifies the vittual- key code or scan code for a ae How this parameter is in- 
terpreted depends on the value of the fuMapType parameter 


fuMapType 
Specifies the translation to ian If this perarister is 0, the uKeyCode pa- 
rameter is a virtual-key code and is translated into its corresponding scan code. 
If fuMapType is 1, uKeyCode is a scan code and is translated to a virtual-key 
code. If fuMapType is 2, uKeyCode is a virtual-key code and is translated to an 
unshifted ASCII value. Other values are reserved. | 
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Return Value 


See Also 


MapWindowPoints 


The return value depends on the value of the uKeyCode and fuMapType parame- 


ters. For more information, see the description of the fuMapType parameter. 


OemKeyScan, VkKeyScan 


void MapWindowPoints(hwndFrom, hwndTo, lppt, cPoints) 


HWND hwndFrom; 
HWND hwndTo; 
POINT FAR® [ppt; 
UINT cPoints; 


_ Parameters 


/* handle of window to be mapped from **/ 
/* handle of window to be mapped to | 
/* address of structure array with points to map aa 
/* number of structures in array / 


The MapWindowPoints function converts (maps) a set of points from a coordi- 
nate space relative to one window to a coordinate space relative to another win- 
dow. | 


hwndF rom | 
Identifies the window from which points are converted. If this parameter is 
NULL or HWND_DESKTOP, the points are assumed to be in screen coordi- 
nates. | 


hwndTo | 
Identifies the window to which points are converted. If this parameter is NULL 
or HWND_DESKTOP, the points are converted to screen coordinates. 


[ppt 
Points to an array of POINT structures that contain the set of points to be con- 
verted. This parameter can also point to a RECT structure, in which case the 
cPoints parameter should be set to 2. The POINT structure has the following 
form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 
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For a full description of these structures, see the Microsoft Windows Program- — 
mer’s Reference, Volume 3. 


cPoints 
Specifies the number of POINT structures in the array pointed to by the i pa- 
rameter. 
Return Value This function does not return a value. 
See Also ClientToScreen, ScreenToClient 


MemManinfo on the EE] 


#include <toolhelp.h> 


BOOL MemManInfo(/pmmi) : . 
eS FAR* lpmmi; /* address of MEMMANINEO structure a 


The MemManInfo function fills the specified structure with status and peo. 
ance information about the memory manager. This function is most useful in 386° 
enhanced mode but can also be used in standard mode. 


Parameters Ipmmi 
Points to a MEMMANINFO structure that will receive information about the 
memory manager. The MEMMANINFO structure has the following form: 


#include <toolhelp.h> 


typedef struct tagMEMMANINFO { /* mmi. */ 
DWORD dwSize; 
DWORD dwLargestFreeBlock; 
DWORD dwMaxPagesAvai lable; 
DWORD dwMaxPagesLockable; 
~DWORD dwlotalLinearSpace; 
~DWORD dwTotalUnlockedPages; 
DWORD dwFreePages; 
~DWORD dwTotal Pages; 
DWORD dwFreeLinearSpace; 
~DWORD dwSwapFilePages; 
WORD wPageSize; 
} MEMMANINEO; 


For a full description of this structure, see the M. ficrosoft Windows Program- 
mer’s Reference, Volume Ss, 
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Return Value 


Comments 


MemoryRead 


The return value is nonzero if the function is successful. Otherwise, it 1s zero. 


This function is included for advisory purposes. 


Before calling MemManInfo, an application must initialize the MEM- 
MANINFO structure and specify its size, in bytes, in the dwSize member. 


#include <toolhelp.h> 

DWORD MemoryRead(wSel, dwOffset, IpvBuf, dwcb) 

WORD wel; /* selector of global heap object i 

DWORD dwOffset; /* offset to object i | 

void FAR* [pvBuf; /* address of buffer to read to i | 

DWORD dwcb; /* number of bytes to read i 
The MemoryRead function copies memory from the specified global heap object 
to the specified buffer. 

Parameters wSel 


Return Value 


Comments 


Specifies the global heap object from which to read. This value must be a selec- 
tor on the global heap; if the value is an alias selector or a selector in a tiled 
selector array, MemoryRead will fail. 


dwOffset | 
Specifies the offset in the object specified in the wSe/ parameter at which to 
begin reading. The dwOffset value may point anywhere within the object; it 
may be greater than 64K if the object is larger than 64K. 

[pvBuf | 
Points to the buffer to which MemoryRead will copy the memory from the ob- 
ject. This buffer must be large enough to contain the entire amount of memory 
copied to it. If the application is running under low memory conditions, lpvBuf 
should be in a fixed object while MemoryRead copies data to it. 


dwcb 


_ Specifies the number of bytes to copy from the object to the buffer pointed to 
by JnvRuf. 


| The return value is the number of bytes copied from wSel to IpvBuf. If wSel is in- 
valid or if dwOffset is out of the selector’s range, the return value is zero. 


The MemoryRead function enables developers to examine memory without 
consideration for selector tiling and aliasing. MemoryRead reads memory in 


See Also 
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read-write or read-only objects. This function can be used in any size object 
owned by any task. It is not necessary to compute selector array offsets. 


The MemoryRead and MemoryWrite functions are designed to read and write 
objects loaded by the LoadModule function or allocated by the GlobalAlloc func- 
tion. Developers should not split off the selector portion of a far pointer and use 


_ this as the value for wSel, unless the selector is known to be on the global heap. 


MemoryWrite 


‘MemoryWrite : [aad 


Return Value | 


#include <toolhelp.h> 
DWORD MemoryWrite(wSel, dwOffset, lpvBuf, dwcb) 
WORD wSel; _ /* selector of global heap object 4 | 
DWORD dwOffset; /* offset to object */ 
void FAR* IpvBuf; /* address of buffer to write from ‘a | 
DWORD dwcb; /* number of bytes to write | a 
7 The MemoryWrite function copies memory from the specitied buffer to the 
specified global heap object. 
Parameters wSel 


Specifies the global heap object to which MemoryWrite will write. This value 
must be a selector on the global heap; if the value is an alias selector or a selec- 
tor in a tiled selector array, MemoryWrite will fail. 


dwOffset | | 
Specifies the offset in the object at which to begin writing. The dwOffset value 
may point anywhere within the object; it may be greater than 64K if the object 
is larger than 64K. 


IpvBuf 
Points to the buffer from which MemoryWrite will copy the memory to the ob- 


ject. If the application is running under low memory conditions, [pvBuf should 
be ina fixed object while Memory Write copies data from it. 


| dweb 


Specifies the number of bytes 1 to copy to . the object from the buffer el eal to 
by lpvBuf. 


The return value is the number of bytes copied from /pvBuf to wSel. If the selector 
is invalid or if dwOffset is out of the selector’s range, the return value is zero. 
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Comments The MemoryWrite function enables developers to modify memory without con- 
sideration for selector tiling and aliasing. MemoryWrite writes memory in read- 
write or read-only objects. This function can be used in any size object owned by 
any task. It is not necessary to make alias objects writable or to compute selector 
array offsets. 


The MemoryRead and MemoryWrite functions are designed to read and write 
objects loaded by the LoadModule function or allocated by the GlobalAlloc func- 
tion. Developers should not split off the selector portion of a far pointer and use 
this as the value for wSel, unless the selector is known to be on the global heap. 


See Also MemoryRead 


MessageBeep [2.x | 


void MessageBeep(uAlert) 
UINT wAlert; /* alert level si 


The MessageBeep function plays a waveform sound corresponding to a given sys- 
tem alert level. The sound for each alert level is identified by an entry in the 
[sounds] section of the WIN.INI initialization file. 


Parameters uAlert 
Specifies the alert level. This parameter can be one of the following values: 
Value Meaning 
—1 Produces a standard beep sound by using the com- 
puter speaker. 
MB_ICONASTERISK Plays the sound identified by the SystemAsterisk 


entry in the [sounds] section of WIN.INI. 


MB_ICONEXCLAMATION Plays the sound identified by the System- 
Exclamation entry in the [sounds] section of 


| | WIN.INI. 7 
MB_ICONHAND Plays the sound identified by the SystemHand 
entry in the [sounds] section of WIN.INI. 
MB_ICONQUESTION Plays the sound identified by the SystemQuestion 
entry in the [sounds] section of WIN.INI. 
MB_OK Plays the sound identified by the SystemDefault 


entry in the [sounds] section of WIN.INI. 


Return Value | This function does not return a value. 


Comments 


See Also 


MessageBox 
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Méssapetiens returns control to the caller after queuing the sound and slaved the 
sound asynchronously. | 


If it cannot play the specified alert sound, MessageBeep attempts to play the sys- 
tem default sound. If it cannot play the system default sound, the function pro- 
duces a standard beep sound by using the computer speaker. 


The user can disable the warning beep by using the Windows Control vane appli- 
cation Sounds. | = 


_ FlashWindow, MessageBox 


int MessageBox(hwndParent, [pszText, IpszTitle, fuStyle) 


HWND hwndParent; 


LPCSTR IpszText; 
LPCSTR IpszTitle; 
UINT fuStyle; 


Parameters 


/* handle of parent window **/ 
/* address of text in message box i 
/* address of title of message box */ 
/* style of message box */ 


The MessageBox function creates, displays, and operates a message-box window. 
The message box contains an application-defined message and title, plus any com- 
bination of the predefined icons and push buttons described in the fuStyle parame- 
ter. | | * 


hwndParent 
Identifies the parent window of the message box to be created. If this parameter 
is NULL, the message box will have no parent window. 


lpszText | 
Points to a null-terminated string containing the meee to be displayed. 


| lpszTitle 


- Points toa null- terminated string to be used for the dialog box ute. If this pa-_ 
rameter is NULL, the default title Error is used. 


fuStyle | 
‘Specifies the contents and behavior of the dialog box. ue parameter can be a 
combination of the following values: 


Value , | Meaning 


MB_ABORTRETRYIGNORE The message box contains three Ns buttons: 
| , 7 | Abort, Retry, and — 
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Value 


MB_APPLMODAL 


MB_DEFBUTTON1 


MB_DEFBUTTON2 
MB_DEFBUTTON3 
MB_ICONASTERISK 
MB_ICONEXCLAMATION 


MB_ICONHAND 
MB_ICONINFORMATION 


MB_ICONQUESTION 


MB_ICONSTOP 
MB_OK 
MB_OKCANCEL 


MB_RETRYCANCEL 


MB_SYSTEMMODAL 


Meaning 


The user must respond to the message box — 
before continuing work in the window identified 
by the hwndParent parameter. However, the user 
can move to the windows of other applications 
and work in those windows. | 


~MB_APPLMODAL is the default if 


neither MB_SYSTEMMODAL nor 
MB_TASKMODAL is specified. 


The first button is the default. Note that the first 
button is always the default unless 
MB_DEFBUTTON2 or MB_DEFBUTTON3 is 
specified. 

The second button is the default. 

The third button is the default. 

Same as MB_ICONINFORMATION. 


An exclamation-point icon appears in the mes- 
sage box. 


Same as MB_ICONSTOP. 


An icon consisting of a lowercase letter “T’ in a 
circle appears in the message box. 


A question-mark icon appears in the message 
box. 


A stop-sign icon appears in the message box. 
The message box contains one push button: OK. 


The message box contains two push buttons: 


OK and Cancel. 


The message box contains two push buttons: 
Retry and Cancel. 


All applications are suspended until the user re- 
sponds to the message box. Unless the applica- 
tion specifies MB_ICONHAND, the message 
box does not become modal until after it is 
created; consequently, the parent window and 
other windows continue to receive messages re- 
sulting from its activation. System-modal mes- 
sage boxes are used to notify the user of serious, 
potentially damaging errors that require immedi- 
ate attention (for example, running out of 
memory). 


Return Value 


Comments 
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Value Meaning 


MB_TASKMODAL Same as MB_APPLMODAL except that all the 
top-level windows belonging to the current task 

are disabled if the hwndParent parameter is 
NULL. This flag should be used when the 
calling application or library does not have a 
window handle available but still needs to pre- 
vent input to other windows in the current appli- 
cation without suspending other applications. 


MB_YESNO The message box contains two push buttons: Yes — 
and No. 
MB_YESNOCANCEL _ The message box contains three push buttons: 


Yes, No, and Cancel. 


Wee 


The return value is zero if there is not enough memory to create the message box. 


Otherwise, it is one of the following menu-item values returned by the dialog box: | 


Value Meaning 


IDABORT Abort button was selected. 
IDCANCEL Cancel button was selected. 
IDIGNORE Ignore button was selected. 


IDNO No button was selected. 
IDOK OK button was selected. 
IDRETRY Retry button was selected. 


IDYES Yes button was selected. 


If a message box has a Cancel button, the IDCANCEL value will be returned if 
either the ESc key is pressed or the Cancel button is selected. If the message box 
has no Cancel button, pressing ESC has no effect. 


When a system-modal message box is created to indicate that the system is low on 
memory, the strings pointed to by the /pszText and [pszTitle parameters should not 
be taken from a resource file, because an attempt to load the resource may fail. 


When an application calls the MessageBox function and specifies the 
MB_ICONHAND and MB_SYSTEMMODAL flags for the fuStyle parameter, 
Windows displays the resulting message box regardless of available memory. 
When these flags are specified, Windows limits the length of the message-box text 
to three lines. Windows does not automatically break the lines to fit in the message 
box, however, so the message string must contain carriage returns to break the 


lines at the appropriate places. 


If a message box is created while a dialog box is present, use the handle of the 


dialog box as the hwndParent parameter. The hwndParent parameter should not 
identify a child window, such as a control in a dialog box. | 
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Following are the various system icons that can be used in a message box: 


g> MB_ICONHAND and MB_ICONSTOP 


MB_ICONQUESTION 
® MB_ICONEXCLAMATION 


iL MB_ICONASTERISK and MB_ICONINFORMATION 


See Also _ FlashWindow, MessageBeep 
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_ LRESULT CALLBACK MessageProc(code, wParam, [Param) 


int code; /* message type | sf 
WPARAM wParam; /* undefined sf 
LPARAM [Param; /* address of structure with message data */ 


The MessageProc function is an application- or library-defined callback function 
that the system calls after a dialog box, message box, or menu has retrieved a mes- 
sage, but before the message is processed. The callback function can process or 

_ modify the messages. 


Parameters code 
Specifies the type of message being processed. This parameter can be one of 
the following values: 


Value Meaning 
| MSGF_DIALOGBOX __ Messages inside a dialog box or message box procedure 
are being processed. 
MSGF_MENU Keyboard and mouse messages in a menu are being 
processed. 3 
3 ree If the code parameter is less than zero, the callback function must pass the mes- 


sage to CallNextHookEx without further processing and return the value re- 
turned by CallNextHookEx. 


wParam | 
Specifies a N ULL value. 


Return Value 


Comments | 


See Also 


ModifyMenu 
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lParam 
Points to an MSG structure. The MSG structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. , 


The callback function should return a nonzero value if it processes the message; it 
should return zero if it does not process the message. _ 


The WH_MSGFILTER filter type is the any task-specific filter. A ‘acts may in- 
stall this filter. 


An application must install the callback function by specifying the 
WH_MSGFILTER filter type and the procedure-instance address of the callback 
function in a call to the SetWindowsHookEx function. 


MessageProc i is a placeholder for the library-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the library’s 
module-definition file. 


CallNextHookEx, SetWindowsHookEx 


BOOL ModifyMenu(hmenu, idltem, fuFlags, idNewltem, lpNewItem) 
i 


HMENU hmenu; /* handle of menu 
_UINT idltem; _/* menu-item identifier | 
UINT fuFlags; /* menu-item flags i | 
UINT idNewltem; /* new menu-item identifier */ 
LPCSTR /pNewltem; /* menu-item content **/ 
| _ The ModifyMenu function changes an existing menu item. 
Parameters hmenu 


Identifies the menu to change. 
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Return Value 


Comments 


idltem | 
Specifies the menu item to change, as determined by the fuFlags parameter. 
When the fuF lags parameter is MF_BYCOMMAND, the id/tem parameter 
specifies the menu-item identifier. When the fuFlags parameter is MF_BY- 
POSITION, the id/tem parameter specifies the zero-based position of the menu 
item. 


fuFlags 
Specifies how the id/tem parameter is interpreted and information about the 
changes to be made to the menu item. It consists of one or more values listed in 
the following Comments section. 


idNewltem 
Specifies either the identifier of the modified menu item or, if fuF lags is set to 
MF_POPUP, the menu handle of the pop-up menu. 


lpNewItem 
Specifies the content of the changed menu item. If fuF lags is set to 
MF_STRING (the default), /pNew/tem is a long pointer to a null-terminated 
string. If fuF lags is set to MF_BITMAP instead, /pNew/tem contains a bitmap 
handle in its low-order word. If fuF lags is set to MF_OWNERDRAW, 
[pNewltem specifies an application-defined 32-bit value that the application 
can use to maintain additional data associated with the menu item. This 
32-bit value is available to the application in the itemData member of the 
MEASUREITEMSTRUCT or DRAWITEMSTRUCT structure pointed to 
by the /Param parameter of the WM_MEASUREITEM or WM_DRAWITEM 
message. These messages are sent when the menu item is initially displayed or 
is changed. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


If the ModifyMenu function replaces a pop-up menu associated with the menu 
item, it destroys the old pop-up menu and frees the memory used “ the pop-up 
menu. 


Whenever a menu changes (whether or not it is in a window that is displayed), the 
application should call DrawMenuBar. To change the attributes of existing menu 
items, it is much faster to use the CheckMenultem and EnableMenultem func- 
tions. 


Each of the following groups lists flags that should not be used together: 
=» MF BYCOMMAND and MF_BYPOSITION 


= MF_DISABLED, MF_ ENABLED, and MF_ GRAYED 
= MF_BITMAP, MF_STRING, MF_ OWNERDRAW, and MF_SEPARATOR 
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=» MF _MENUBARBREAK and MF_MENUBREAK 
= MF_ CHECKED and MF_UNCHECKED 


The following list describes the flags that may be set in the fuFlags parameter: 


Value 


MF_BITMAP 
MF_BYCOMMAND 
MF_BYPOSITION 
MF_CHECKED 
MF_DISABLED 
MF_ENABLED 


MF_GRAYED 


MF_MENUBARBREAK 
MF_MENUBREAK 


MF_OWNERDRAW 


MF_POPUP 


Meaning 


Uses a bitmap as the menu item. The low-order word of 
the IpNewItem parameter contains the handle of the bit- 
map. | = 
Specifies that the id/tem parameter gives the menu-item 
identifier. This is the default if neither 
MF_BYCOMMAND nor MF_POSITION is set. 


Specifies that the id/tem parameter gives the position of 
the menu item to be changed rather than the menu-item 

identifier. | 

Places a check mark next to the menu item. If the appli- 
cation has supplied check-mark bitmaps (see SetMenu- 
ItemBitmaps), setting this flag displays the check-mark 
bitmap next to the menu item. 

Disables the menu item so that it cannot be siectea. but 
does not gray (dim) it. 


Enables the menu item so that it can be selected and re- 


stores it from its grayed state. 


Disables the menu item so that it cannot be selected and 
grays it. 

Same as MF_MENUBREAK except, for) pop-up menus, 
separates the new column from the old column with a 
vertical line. | 
Places the menu item on a new line for static menu-bar 
items. For pop-up menus, this flag places the item in a 


new column, with no dividing line between the columns. 


Specifies that the menu item is an owner-drawn 
item. The window that owns the menu receives a 


WM_MEASUREITEM message when the menu is dis- 


played for the first time to retrieve the height and width © 


of the menu item. The WM_DRAWITEM message is 
then sent whenever the owner must update the visual ap- 
pearance of the menu item. This option is not valid for a 
top-level menu item. 


Specifies that the item has a pop-up menu associated 
with it. The idNewltem parameter specifies a handle of a 
pop-up menu to be associated with the menu item. Use 
this flag for adding either a top-level pop-up menu or a 
hierarchical pop-up menu to a pop-up menu item. 
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Value Meaning 


MF_SEPARATOR Draws a horizontal dividing line. This line cannot be 
grayed, disabled, or highlighted. You can use this flag 
only in a pop-up menu. The /pNewltem and idNewltem 
parameters are ignored. 


MF_STRING Specifies that the menu item is a character string; the 
IpNewltem parameter points to the string for the menu 
item. 

MF_UNCHECKED Does not select (place a check mark next to) the menu 


item. No check mark is the default condition if neither 
MF_CHECKED nor MF_UNCHECKED is set. If the ap- 
plication has supplied check-mark bitmaps (see the Set- 
MenultemBitmaps function), setting this flag displays 
the “check mark off’ bitmap next to the menu item. 


See Also CheckMenultem, DrawMenuBar, EnableMenulItem, SetMenultemBitmaps 


ModuleFindHandle aa 


‘#include <toolhelp.h> 
HMODULE ModuleFindHandle(/pme, hmod) 
MODULEENTRY FAR® Ipme; /* address of MODULEENTRY structure */ 
HMODULE hmod; /* handle of module */ 


The ModuleFindHandle function fills the specified structure with information 
that describes the given module. 


Parameters itis 
| Points to a MODULEENTRY structure that will receive information about the 
module. The MODULEENTRY structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagMODULEENTRY { /* me */ 
DWORD = dwSize; 
char szModule[MAX_MODULE_NAME + 1]; 
HMODULE nmoduie; 
WORD wcUsage; 
char szExePathLMAX_ PATH + 1]; 

| WORD wNext; 

} MODULEENTRY; 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hmod 
Identifies the module to be described. 


Return Value The return value is the handle of the given module if the function is successful. 
Otherwise, it is NULL. 


Comments The ModuleFindHandle function returns information about a currently loaded 
| module whose module handle is known. 


This function can be used to begin a walk through the list of all currently loaded 
modules. An application can examine subsequent items in the module list by using 
the ModuleNext function. 


Before calling ModuleFindHandle, an application must initialize the _ 
MODULEENTRY structure and specify its size, in bytes, in the dwSize member. 


See Also — ModuleFindName, ModuleFirst, ModuleNext 


ModuleFindName | a . oe ae 


#include <toolhelp.h> 

HMODULE ModuleFindName(lpme, IpszName) 

MODULEENTRY FAR?*® [pme; /* address of MODULEENTRY structure **/ 
LPCSTR [pszName; /* address of module name =] 


The ModuleFindName function fills the specified structure with information that 
describes the module with the specified name. 


Parameters Ipme 
Points to a MODULEENTRY structure that will receive information about the 
module. The MODULEENTRY structure has the following form: 
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Return Value 


Comments 


See Also 


ModuleFirst 


#tinclude <toolhelp.h> 


typedef struct tagMODULEENTRY { /* me */ 


DWORD dwSize; 

char szModule[MAX_MODULE_NAME + 1];. 
HMODULE hModule; 

WORD wcUsage; 

char szExePath[MAX_ PATH + 1]; 

WORD wNext; 


} MODULEENTRY; 
For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


IpszName | 
Specifies the name of the module to be described. 


The return value is the handle named in the IpszName parameter, if the function is 
successful. Otherwise, it is NULL. 


The ModuleFindName function returns information about a currently loaded 
module by looking up the module’s name in the module list. 


This function can be used to begin a walk through the list of all currently loaded 
modules. An application can examine subsequent items in the module list by using 
the ModuleNext function. 


Before calling ModuleFindName, an application must initialize the 
MODULEENTRY structure and specify its size, in bytes, in the dwSize member. 


ModuleFindHandle, ModuleFirst, ModuleNext 


#include <toolhelp.h> 


BOOL ModuleFirst(/pme) 
MODULEENTRY FAR* Ipme; 


The ModuleFirst function fills the specified structure with information that de- 
scribes the first module in the list of all currently loaded modules. 


/* address of MODULEENTRY structure 


a 
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Parameters lpme 
Points tt a MODULEENTRY structure that will receive information about the 
first module. The MODULEENTRY structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagMODULEENTRY {. /* me */ 
DWORD dwSize; 
char szModule[MAX_MODULE_NAME + 1]; 
HMODULE hModule; | 
WORD wcUsage; 
char szExePath[MAX_ PATH + ij; 
WORD wNext; _ 

} MODULEENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The ModuleFirst function can be used to begin a walk through the list of all cur- | 
| rently loaded modules. An application can examine subsequent items in the mod- 
ule list by using the ModuleNext function. | 


Before calling ModuleFirst, an application must initialize the MODULEENTRY 
structure and specify its size, in bytes, in the dwSize member. 


See Also ModuleFindHandle, ModuleFindName, ModuleNext 


ModuleNext [3.4] 
#include <toolhelp.h> 


BOOL ModuleNext(/pme) | hore | 
MODULEENTRY FAR* Ipme; /* address of MODULEENTRY structure. ur 


The ModuleNext function fills the specified structure with information that de- 
‘scribes the next module in the list of all currently loaded modules. - | 


Parameters — Ipme 
Points to a MODULEENTRY structure that will receive information about he | 
next module. The MODULEENTRY structure has the following form: 
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Return Value 


Comments 


See Also 


MouseProc 


#Hinclude <toolhelp.h> 


typedef struct tagMODULEENTRY { /* me */ 
DWORD dwSize; 
char szModuleLMAX_MODULE_NAME + 1]; 
HMODULE hModule; 
WORD wcUsage; 
char sZExePath[MAX_ PATH + 1]; 
WORD wNext; 

} MODULEENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The ModuleNext function can be used to continue a walk through the list of all 
currently loaded modules. The walk must have been started by the ModuleFirst, 
ModuleFindName, or ModuleFindHandle function. 


ModuleFindHandle, ModuleFindName, ModuleFirst 


LRESULT CALLBACK MouseProc(code, wParam, lParam) 


int code; 
WPARAM wParam; 
LPARAM /Param; 


Parameters 


/* process-message flag +] 
/* message identifier | sa | 
/* address of MOUSEHOOKSTRUCT structure */ 


The MouseProc function is a library-defined callback function that the system 
calls whenever an application calls the GetMessage or PeekMessage function and 
there is a mouse message to be processed. 


code | 
Specifies whether the callback function should process the message or call the 
CallNextHookEx function. If this value is less than zero, the callback function 
should pass the message to CallNextHookEx without further processing. If this 
value is HC NOREMOVE., the application is using a PeekMessage function 
with the PM_NOREMOVE option, and the message will not be removed from 
the system queue. 


wParam 
Specifies the identifier of the mouse message. 
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lParam 
Points to a MOUSEHOOKSTRUCT structure containing information about _ 
the mouse. The MOUSEHOOKSTRUCT structure has the following form: 


typedef struct tagMOUSEHOOKSTRUCT { /* ms */ 
POINT pt; 
HWND hwnd; 
UINT wHitTestCode; 
DWORD dwExtralnfo; 
} MOUSEHOOKSTRUCT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


The callback function should return 0 to allow the system to process the message; 
it should return 1 to discard the message. ) 


Comments This callback function should not install a J ournalPlaybackProc callback func- 
tion. 


An application must install the callback function by specifying the WH_MOUSE 
filter type and the procedure-instance address of the callback function in a call to 
the SetWindowsHookEx function. 


MouseProc is a placeholder for the library- -defined function name. The actual Gee 
name must be exported by including it in an EXPORTS statement in the library’ s 
module-definition file. 


- See Also CallNextHookEx, GetMessage, PeekMessage, Set WindowsHookEx 
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DWORD MoveTo(hdc, nXPos, nYPos) 


HDC hdc; /* handle of device context _ ‘7 
_ IntnXPos; —_/* x-coordinate of new position */ 
int nYPos; /* y-coordinate of new position =} 


The MoveTo function moves the current position to the specified coordinates. 


Parameters | hdc 
: | Identifies the device context. 


nXPos ‘ i | 
Specifies the logical X- -coordinate - ther new y position. 


646 MoveToEx 


Return Value 


Example 


See Also 


Move IoEx 


nYPos 
Specifies the logical y-coordinate of the new position. — 


The low-order word of the return value contains the logical x-coordinate of the pre- 
vious position, if the function is successful; the high-order word contains the logi- 
cal y-coordinate. | 


The following example uses the MoveTo function to set the current position and 
then calls the LineTo function. The example uses POINT structures to store the 
coordinates. 


HDC hdc; 
POINT ptStart = { 12, 12 }; 
POINT ptEnd = { 128, 135 }; 


| MoveTo(hdc, ptStart.x, ptStart.y); 


LineTo(hdc, ptEnd.x, ptEnd.y); 


GetCurrentPosition, LineTo 


BOOL MoveToEx(hdc, nX, nY, lpPoint) 


HDC hdc; /* handle of device context | | */ 
int nX; /* x-coordinate of new position | | 
int nY; /* y-coordinate of new position a | 
POINT FAR® [pPoint; /* pointer to structure for previous position sf 
The MoveToEx function moves the current position to the point specified by the 
nX and nY parameters, optionally returning the previous position. 
Parameters hdc 
Identifies the device context. 
nX 


Specifies the logical x-coordinate of the new position. 


ny | 
Specifies the logical y-coordinate of the new position. 
IpPoint | | 
Points to a POINT structure in which the previous current position will be 


stored. If this parameter is NULL, no previous position is returned. The POINT 
_ structure has the following form: 


Return Value 


See Also 


MoveWindow 
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typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if the call is successful. Otherwise, it 1s zero. 


MoveTo © 


BOOL MoveWindow(hwnd, nLeft, nTop, nWidth, nHeight, fRepaint) 
*). 


HWND hwnd; 
int nLeft; 

int nTop; 

int nWidth; 
int nHeight; 


BOOL fRepaint; | 


Parameters 


/* handle of window 


/* left coordinate * 
/* top coordinate =) 
/* width sa 
/* height. a 
_ /* repaint flag +] 


The MoveWindow function changes the position and dimensions of a window. 
For top-level windows, the position and dimensions are relative to the upper-left 
corner of the screen. For child windows, they are relative to the upper-left corner 
of the parent window’s client area. | 


hwnd 
Identifies the window to be changed. 


nLeft 
Specifies the new position of the left side of the window, 


nTop 
Specifies the new position of the top of the window. 


nWidth 
Specifies the new width of the window. 


nHeight 
Specifies the new height of the window. 


fRepaint 
Specifies whether the window is to ‘be = repainted. If this parameter is TRUE, the 


window receives a WM_PAINT message. If this parameter is FALSE, no re- 
painting of any kind occurs. This applies to the client area, the nonclient area 
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Return Value 


Comments 


Example 


See Also 


MulDiv 


(including the title and scroll bars), and any part of the parent window un- 
covered as a result of the moved window. When this parameter is FALSE, the 
application must explicitly invalidate or redraw any parts of the window and 
parent window that must be redrawn. | 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The MoveWindow function sends a WM_GETMINMAXINFO message to the © 
window being moved, giving it an opportunity to modify the default values for the 
largest and smallest possible windows. If the MoveWindow parameters exceed 
these values, they will be replaced by the minimum or maximum values specified 
in the WM_GETMINMAXINFO message. 


The following example changes the dimensions of a child window in response to a 
WM_SIZE message. In this example, the child window would always fill the 
client area of the parent window. 


case WM_SIZE: 
MoveWindow(hwndChild, @, @, LOWORD(1Param), HIWORD(1Param), 
TRUE); 
break; 


ClientToScreen, GetWindowRect, ScreenToClient, SetWindowPos 


int MulDiv(nMultiplicand, nMultiplier, nDivisor) 


int nMultiplicand; 
int nMultiplier; 
int nDivisor; 


Parameters 


/* 16-bit signed multiplicand */ 
/* 16-bit signed multiplier */ 
/* 16-bit signed divisor */ 


The MulDiv function multiplies two 16-bit values and then divides the 32-bit re- 
sult by a third 16-bit value. The return value is the 16-bit result of the division, 
rounded up or down to the nearest integer. 


nMultiplicand 
Specifies the multiplicand. 


nMultiplier 
Specifies the multiplier. 


nDivisor 
Specifies the number by which the result of the multiplication 
—(nMultiplicand * nMultiplier) is to be divided. 


Return Value 


See Also 


NetBIOSCall 


_ The NetBIOSCall function allows an application to issue the NETBIOS Interrupt 


Parameters | 


Return Value 


~ Comments 


Example 
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The return value is the result of the multiplication and division if the function is 
successful. The return value is —32,768 if either an overflow occurs or the 
nDivisor parameter is 0. 


CreateFontIndirect, GetDeviceCaps 


5Ch. This function can be called only from assembly-language routines. It is ex- 
ported from KRNL286.EXE and KRNL386.EXE and is not defined in any Win- 
dows peace files. 


- Registers must be set up as required by Interrupt 5Ch before the application calls 


the NetBIOSCall function. 
The register contents are preserved as they are returned by Interrupt 5Ch. 


Applications should use this function instead of directly issuing a NETBIOS 
Interrupt 5Ch. | 


To use this function, an application should declare it in an assembly-language 
routine, as follows: 


extrn NETBIOSCALL: far 


If the application includes CMACROS.INC, the function is declared as follows: 


externFP NetBIOSCal | 


Following is an example of how to use the NetBIOSCall function: 


extrn NETBIOSCALL: far 


— 3set registers 


cCall NetBIOSCall 
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NotifyProc x] 


BOOL CALLBACK NotifyProc(hgibl) 
HGLOBAL heglbl; /* handle of global memory object */ 


The NotifyProc function is a library-defined callback function that the system 
calls whenever it is about to discard a global memory object allocated with the 
GMEM_NOTIFY flag. 


Parameters hglbl 
Identifies the global memory object being discarded. 


Return Value The callback function should return nonzero if the system is to discard the 
memory object, or zero if it should not. 


Comments The callback function is not necessarily called in the context of the application that 
owns the routine. For this reason, the callback function should not assume it is 
using the stack segment of the application. The callback function should not call 
any routine that might move memory. 


The callback function must be in a fixed code segment of a dynamic-link library. 


NotifyProc is a placeholder for the application- defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the eee S 
module-definition statement. 


See Also GlobalNotify 


NotifyRegister — [3.1 | 


#include <toolhelp.h> 

BOOL NotifyRegister(hiask, ipjnCallback, wFlags) — 

HTASK htask; /* handle of task */ 
LPFNN OTIFYCALLBACK ipjnCallback; /* address of callback function x) 
WORD wFlags; _ /* notification flags a 


The NotifyRegister function installs a notification callback function for the given 
task. 


Parameters 


| Return Value 


Callback Function 


Parameters 
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htask 
Identifies the task associated with the callback function. If this parameter is — 
NULL, it identifies the current task. 


[pfnCallback 
Points to the notification callback function that is installed for the task. The ker- 
nel calls this function whenever it sends a notification to the task. 


The callback-function address is normally the return value of a call to Make- 
ProcInstance. This causes the callback function to be entered with the AX reg- 
ister set to the selector of the application’s data segment. Usually, an exported 
function prolog contains the following code: 


mov ds,ax 


wFlags 
Specifies the optional notifications that the application will receive, in addition 
to the default notifications. This parameter can be NF_NORMAL or any combi- 
nation of the following values: 


Value Meaning 


NF_NORMAL The application will receive the default notifications but 
none of the notifications of task switching, system debug- _ 
‘ging errors, or debug strings. 
NF_TASKSWITCH The application will receive task-switching notifications. 
| To avoid poor performance, an application should not re- 
ceive these notifications unless absolutely necessary. 
NF_RIP The application will receive notifications of system debug- 
_ ging errors. 


The return value is nonzero if the function was successful. Otherwise, it is zero. 


The syntax of the function pointed to by [pfnCallback is as follows: 


BOOL NotifyRegisterCallback(w/D, care 
WORD wID; 
DWORD dwData; 


wlD 
Indicates the type of notification and the value of the dwData parameter. The 
wID parameter may be one of the following values in Windows versions 3.0 
and later: 


Value Meaning 


NFY_DELMODULE - The low- order word of dwData is the ae of the mod- 
ule to be freed. 
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Return Value 


Value | Meaning 

NFY_EXITTASK ___ The low-order byte of dwData contains the program exit 
code. 

NFY_FREESEG The low-order word of dwData is the selector of the seg- 
ment to be freed. 

NFY_INCHAR The dwData parameter is not used. The notification call- 
back function should return either the ASCII value for the 
keystroke or NULL. | 

NFY_LOADSEG The dwData parameter points to an NFYLOADSEG 
structure. 

NFY_OUTSTR The dwData parameter points to the string to be displayed. 

NFY_RIP The dwData parameter points to an NFYRIP structure. 

NFY_STARTDLL The dwData parameter points to an NFYSTARTDLL 

| structure. 

NFY_STARTTASK The dwData parameter is the CS:IP of the starting address 

of the task. | 


NFY_UNKNOWN The kernel returned an unknown notification. 


In Windows version 3.1, wID may be one of the following values: 


Value Meaning 

NFY_LOGERROR | The dwData parameter points to an NFYLOG- 
ERROR structure. 

- NFY_LOGPARAMERROR The dwData parameter points to an NFYLOG- 
_ PARAMERROR structure. 

NFY_TASKIN | - The dwData parameter is undefined. The callback 
function should call the GetCurrentTask function. 

NFY_TASKOUT The dwData parameter is undefined. The callback 


function should call GetCurrentTask. 


dwData 
_ Specifies data, or specifies a pointer to data, or is undefined, depending on the 
value of wID. 


The return value of the callback function is nonzero if the callback function 
handled the notification. Otherwise, it is Zero and the notification is passed to 
other callback functions. 
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value. Typically, the notification callback function cannot use any Windows func- 
tion, with the exception of the Tool Helper functions and PostMessage. 


Notify RegisterCallback is a placeholder for the application-defined function 
name. The actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 
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See Also InterruptRegister, InterruptUnRegister, MakeProcInstance, 
NotifyUnRegister, TerminateApp 


NotifyUnRegister [3a] 


#include <toolhelp.h> 


BOOL NotifyUnRegister(htask) 
HTASK htask; /* handle of task */ 


The NotifyUnRegister function restores the default notification handler. 


Parameters htask | 
Identifies the task. If htask is NULL, it identifies the current task. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments After this function is executed, the given task no longer receives notifications from 
the kernel. | | | 
— See Also | InterruptRegister, InterruptUnRegister, NotifyRegister, TerminateApp 


OemKeyScan | 


DWORD OemKeyScan(uOemChar) | 
UINT uOemChar; /* OEM ASCII character : */ 


The OemKeyScan function translates (maps) OEM ASCII codes 0 through OxFF 
to their corresponding OEM scan codes and shift states. | 


Parameters uOemChar 
Specifies the ASCII value of the OEM character. 


Return Value The low-order word of the return value contains the scan code of the specified 
OEM character; the high-order word contains flags that indicate the shift state: If 
bit 1 is set, a SHIFT key is pressed; if bit 2 is set, a CTRL key is pressed. Both the 
low-order and high-order words of the return value contain —1 if the character is 
not defined in the OEM character tables. 
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Comments The OemKeyScan function does not translate characters that require CTRL+ALT or 
dead keys. Characters not translated by this function must be copied by simulating 
input, using the ALT+ keypad mechanism. For this to work, the NUM LOCK key 
must be off. | 


This function calls the VkKeyScan function in recent versions of the keyboard 
device drivers. 


OemKeyScan allows an application to send OEM text to another application by 
simulating keyboard input. It is used specifically for this purpose by Windows in 
386 enhanced mode. | 


See Also VkKeyScan 


OemToAnsi Oe | ex | 


void OemToAnsi(hpszOemStr, hpszWindowsStr) 
const char _huge* hpszOemStr; —_/* address of string to translate */ 
char _huge* hpszWindowsStr; /* address of translated string buffer **/ 


The OemToAnsi function translates a string from the OEM-defined character set 
into the Windows character set. 


Parameters _ hpszOemStr_. 
| | Points to a null-terminated string of characters from the OEM-defined character 
set. 
hpszWindowsStr 
| Points to the location where the translated string is to be copied. To translate 
the string in place, the hpszWindowsStr parameter can be the same as the 
hpszOemStr parameter. P 


Return Value This friction does not return a value. 


See Also AnsiToOem, OemToAnsiBuff 
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OemToAnsiBuif Pax] 


void Oem ToAnsiBuff(/pszOemStr, [pszWindowsStr, cbOemStr) 


LPCSTR [pszOemStr; /* address of OEM character string ia 
LPSTR [pszWindowssStr; /* address of buffer for Windows string */ 
UINT cbOemsStir; /* length of OEM string */ 


The OemToAnsiBuff function translates a string from the OEM-defined character 
set into the Windows character set. 


Parameters IpszOemStr 
Points to a buffer containing one or more characters from the OEM-defined 


character set. 


lpszWindowsStr 
Points to the location where the translated string is to be copied. To translate 


the string in place, the [pszWindowsSir parameter can be the same as the 
lpszOemStr parameter. 


cbOemStr 
Specifies the length, in bytes, of the buffer pointed to by lpszOemStr. If 


cbOemsStr 1s 0, the length is 64K. 
Return Value This function does not return a value. 


See Also AnsiToOem, OemToAnsi 


OffsetClipRgn rex] 


int OffsetClipRen(hdc, nXOffset, nY Offset) 


HDC hdc; /* device-context handle */ 

int nXOffsets /* offset along x-axis a | 

int nYOffset; /* offset along y-axis 7] 
The OffsetClipRgn function moves ie clipping region of the given device by the 
specified offsets. 

Parameters hdc 
| Identifies the device context. 

nX Offset 


Specifies the number of logical units to move left or right. 
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Return Value 


Example 


See Also 


OffsetRect 


void OffsetRect(Iprc, x, y) } 


RECT FAR* Iprc; 
int x; 
int y; 


nY Offset | 
Specifies the number of logical units to move up or down. 


The return value is SIMPLEREGION (region has no overlapping borders), , 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR. 


The following example creates an elliptical region and selects it as the clipping re- 
gion for a device context. The OffsetClipRgn function is called repeatedly to 
move the clipping region from left to right across the screen. Because only the 
new clipping region is redrawn each time the Rectangle function is called, the left 
side of each ellipse remains on the screen when the clipping region moves. When 
the loop has finished, a wide blue line with rounded ends stretches from one side 
of the client area to the other. 


RECT rc; 

HRGN hrgn; 

HBRUSH hbr, hbrPrevious; 
int i; 


GetClientRect(hwnd, &rc); 

hrgn = CreateEllipticRgn(0, 100, 100, 200); 
SelectClipRgn(hdc, hrgn); | 

hbr = CreateSolidBrush(RGB(@, @, 255)); 
hbrPrevious = SelectObject(hdc, hbr); 


for (i = @; i < re.right - 100; i++) { 

OffsetClipRgn(hdc, 1, Q); 

Rectangle(hdc, rc.left, rc.top, rc.right, rc.bottom); 
} 


SelectObject(hdc, hbrPrevious); 


DeleteObject(hbr); 
DeleteObject(hrgn); 


CreateEllipticRgn, SelectClipRgen 


/* address of structure with rectangle +] 
/* horizontal offset a 
/* vertical offset a 


The OffsetRect function moves the given rectangle by the specified offsets. 


Parameters 


Return Value 


Comments | 


See Also 


OffsetRgn 
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lprc 
Points to a RECT structure that contains the coordinates of the ere to be 
moved. The RECT structure has the following form: , 


typedef struct tagRECT { /* rc x*/ 
int left; 
int top; 
int right; 
int bottom; 
} RECT: 


For a full description of this structure, see the Microsoft Windows Program- 
-mer’s Reference, Volume 3. 


x 
_ Specifies the amount to move left or right. It must be negative to move left. 


Specifies the amount to move up or down. It must be negative to move up. 
This function does not return a value. 
The coordinate values of a rectangle must not be greater than 32,767 or less than 
—32,768. The x and y oe must be chosen carefully to prevent invalid 


rectangles. 


InflateRect, IntersectRect, UnionRect 


int OffsetRgen(hren, nXOffset, nY Offset) 


HRGN hrgn; 
int nXOffset; 
int nYOffset; 


Parameters 


/* handle of region 7] 
/* offset along x-axis sa 
/* offset along y-axis ay, 


The OffsetRgn function moves the given region by the specified offsets. 


hrgn 
Identifies the region to be moved. 


nX Offset 
Specifies the number of logical units to move left or right. 


nYOffset 
Specifies the number of logical units to move up or down. 
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Return Value 
Comments 


Example 


The return value is SIMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR. 


The coordinate values of a region must not be greater than 32,767 or less than 


—32,768. The nX Offset and nYOffset parameters must be carefully chosen to pre- 
vent invalid regions. 


The following example creates a rectangular region, uses the OffsetRgn function 
to move the region 50 positive units in the x- and y-directions, selects the offset re- 
gion into the device context, and then fills it by using a blue brush: 


HDC hdcLocal; 
HRGN hrgn; 
HBRUSH hbrBlue; 
int RgnType; 


hdcLocal = GetDC(hwnd); 

hrgn = CreateRectRgn(100, 10, 210, 110); 
SelectObject(hdc, hrgn); 

PaintRgn(hdc, hrgn); 


Rgntype = OffsetRgn(hrgn, 50, 50); 
SelectObject(hdc, hrgn); | 


if (RgnType == ERROR) 
TextOut(hdcLocal, 10, 135, "ERROR", 5); 
else if (RgnType == SIMPLEREGION) 
TextOut(hdcLocal, 10, 135, "SIMPLEREGION", 12); 
else if (RgnType == NULLREGION) 
TextOut(hdcLocal, 10, 135, "NULLREGION", 10); 
else 
TextOut(hdcLocal, 10, 135, "Unrecognized value.", 19); 


hbrBlue = CreateSolidBrush(RGB(@, @, 255)); 


-FillRgn(hdc, hrgn, hbrBlue); 


DeleteObject(hrgn); 
DeleteObject(hbrBlue); 
ReleaseDC(hwnd, hdcLocal); 
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OffsetViewportOrg - : a [2x] 


DWORD Offset ViewportOrg(hdc, nX Offset, nYOffset) 


HDC hdc; 
int nXOffset; 
int nYOffset; 


Parameters | 


Return Value 


Comments 


Example 


hdc 


/* handle of device context | 
/* offset along x-axis | | 
/* offset along y-axis a 


The Offset ViewportOrg function modifies the coordinates of the viewport origin . 
relative to the coordinates of the current viewport origin. 7 


Identifies the device context. 


nX Offset | 
Specifies the value, in device units, to add to the x- -coordinate of the current 
origin. 


nY Offset | 
Specifies the value, in device units, to add to the y-coordinate of the current 
origin. 


The low-order word of the return value contains the x-coordinate, in device units, 
of the previous viewport origin, if the function is successful; the high-order word 
contains the y-coordinate. 


The viewport origin is the origin of the device coordinate system for a window. 
By changing the viewport origin, an application can change the way the graphics 
device interface (GDI) maps points from the logical coordinate system. GDI maps 
all points in the logical coordinate system to the viewport in the same way as it 
maps the origin. 


To map points to the right, specify a negative value for the nX Offset parameter. 


- Similarly, to map points down (in the MM_TEXT mapping mode), specify a nega- 


tive value for the nYOffset parameter. 


The following example uses the OffsetWindowOrg and Offset ViewportOrg 
functions to reposition the output of the see ihe as function on the screen: 


HDC hdcMeta; 


~ HANDLE hmf; 


/dcMeta = CreateMetaFile((LPSTR) NULL) 5 


: ie Record the metafile. af; 


PlayMetaFile(hdc, hmf); 
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See Also 


OffsetViewportOrgEx 


OffsetWindowOrg(hdc, -200, -200); 
PlayMetaFile(hdc, hmf); /* MM_TEXT screen output +200 x, +200 y */ 


OffsetViewportOrg(hdc, @, -200); - 
PlayMetaFile(hdc, hmf); /* outputs -200 y from last PlayMetaFile */ 


DeleteMetaFile(hmf); 


GetViewportOrg, OffsetWindowOrg, SetViewportOrg 


BOOL Offset ViewportOrgEx(hdc, nX, nY, [pPoint) 


HDC hdc; 
int nX; 
int nY; 


/* handle of device context | #/ 
/* device units to add to x-coordinate **/ 
/* device units to add to y-coordinate */ 


POINT FAR* IpPoint; /* address of POINT structure i 


Pa rameters 


Return Value 


The Offset ViewportOrgEx function modifies the viewport origin relative to the 


current values. The formulas are written as follows: 


xO1dvO + X 
yOldvO + Y 


xNewV0 
yNewVO 


The new origin is the sum of the current origin and the nX and nY values. 


hdc 
Identifies the device context. 


nxX | 
Specifies the number of device units to add to the current origin’s x-coordinate. 
ny | 
Specifies the number of device units to add to the current origin’s y-coordinate. 
[pPoint 
Points to a POINT structure. The previous viewport origin (in device coordi- 
nates) is placed in this structure. If jpPointis NULL, the previous viewport 
Origin in not returned. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 
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OffsetWindowOrg | 7 [ 2.x | 


DWORD OfifsetWindowOrg(hdc, nXOffset, nYOffset) 


HDC hdc; _ /* handle of device context ca | 
int nX Offset; /* offset along x-axis st 
int nYOffset; /* offset along y-axis © | 


_ The OffsetWindowOrg function modifies the window origin relative to the — 
coordinates of the current window origin. 


Parameters — hdc 
Identifies the device context. 
nxX Offset 
Specifies the value, in logical units, to add to the aime of the current 
origin. 


nYOffset 
Specifies the value, in eeical units, to add t to y-coordinate of the current origin. 


Return Value The low-order word of the return value contains the logical X- -coordinate of the pre- 
vious window origin, if the function i 1S successful; the high- -order word contains 
the logical y-coordinate. | 


Comments - The window, origin is the origin of the logical coordinate system for a window. 
By changing the window origin, an application can change the way the graphics 
device interface (GDI) maps logical points to the physical coordinate system (the 
viewport). GDI maps all points in the logical coordinate system to the viewport in 
the same way as it maps the origin. . | 


To map points to the right, specify a negative value for the nX Offset parameter. | 
Similarly, to map points down (in the MM_TEXT mapping mode), specify a nega- 
tive value for the ny Offset parameter. 


Example The following example uses the OffsetWindowOrg and Offset ViewportOrg 
3 | functions to reposition the output of the PlayMetaFile function on the screen: ° 


HDC hdcMeta; 
HANDLE hmf; 


hdcMeta = CreateMetaFile((LPSTR) NULL); 


. /* Record the metafile. */ 


PlayMetaFile(hdc, hmf); 
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See Also 


OffsetWindowOrgEx 


OffsetWindowOrg(hdc, -200, -200); . 
PlayMetaFile(hdc, hmf); /* MM_TEXT screen output +200 x, +200 y */ 


OffsetViewportOrg(hdc, @, -200); 
PlayMetaFile(hdc, hmf); /* outputs -200 y from last PlayMetaFile */ 


DeleteMetaFile(hmf); 


GetWindowOrg, Offset ViewportOrg, SetWindowOrg 


BOOL OffsetWindowOrgEx(hdc, nX, nY, [pPoint) 


HDC hdc; 
int 2X; 
int nY; 


/* handle of device context a) 
/* logical units to add to x-coordinate **/ 
/* logical units to add to y-coordinate | 


POINT FAR® /pPoint; /* address of POINT structure _ si 


Parameters 


Return Value 


The Offset WindowOrgEx function modifies the viewport origin relative to the 
current values. The formulas are written as follows: 


xNewWO = xO1dWO + X 
yNewWO = yOIdWO + Y 


The new origin is the sum of the current origin and the nX and nY values. 


hdc 
Identifies the device context. 


nx 
Specifies the number of logical units to add to the current origin’s x-coordinate. 


nY 
Specifies the number of logical units to add to the current origin’s y-coordinate. 
[pPoint | 
Points to a POINT structure. The previous window origin (in logical coordi- 
nates) is placed in this structure. If JpPoint is NULL, the previous origin is not 
returned. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


OleActivate 


#include <ole.h> 
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| 3.1 | | 


OLESTATUS OleActivate(/pObject, verb, fShow, flakeF ocus, hwnd, lprcBound) 


LPOLEOBJECT (pObject; /* address of object to activate */ 
UINT verb; /* operation to perform ig 
BOOL /fShow; /* whether to show window a ee 
BOOL fTakeFocus; /* whether server gets focus | */ 
HWND hwnd; /* window handle of destination document */ 
const RECT FAR®* /prcBound; /* bounding rectangle for object display | 
| The OleActivate function opens an object for an operation. Typically, the ys 1S 
edited or played. 
Parameters [pObject 


Points to the object to activate. 


verb — 
Specifies which operation to MPSrOnn (O= the pee verb, | = the secondary 
_ verb, and so on). | | 


{Show 


Specifies whether the window is to be shown. If the window i is to be shown, 
this value is TRUE; otherwise, itis FALSE. a 


flakeFocus 


Return Value 


Specifies whether the server nould get the focus. If the server should get the | 
focus, this value is TRUE; otherwise, it 1S FALSE. This parameter iS relevant 
only if the {Show parameter is TRUE. 4 


hwnd 
Identifies the window of the deeuiicet containing the object. 


lprcBound 
Points to a RECT structure containing the coordinates of the bounding | 
rectangle in which the destination document displays the object. The mapping 
mode of the device context determines the units for these coordinates. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_OBJECT | 
OLE_WAIT HOR _RELEASE 
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Comments | 


See Also 


OleBlockServer 


#include <ole.h> 


Typically, a server is launched in a separate window; editing then occurs asyn- 
chronously. The client is notified of a to the object through the callback 
function. 


A client application might set the {Show parameter to FALSE if a server needed to 
remain active without being visible on the display. (In this case, the application 
would also use the OleSetData function.) 


Client applications typically specify the primary verb when the user double-clicks 
an object. The server can take any action in response to the specified verb. If the 
server supports only one action, it takes that action no matter which value is 
passed in the verb parameter. 


In future releases of the object linking and embedding (OLE) protocol, the hwnd 
and iprcBound parameters will be used to help determine the placement of the 
server’s editing window. 


OleQueryOpen, OleSetData 


OLESTATUS OleBlockServer(/hSrvr) 


LHSERVER /hSrvr; 


Parameters 


Return Value 


Comments 


/* handle of server */ 


The OleBlockServer function causes requests to the server to be queued until the 
server calls the OleUnblockServer function. 


[hSrvr 
Identifies the server for which requests. are to be queued. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be OLE_LERROR_HANDLE. 


The server must call the OleUnblockServer function after calling the OleBlock- 
Server friinction. | 


A server application can use the OleBlockServer and OleUnblockServer func- 
tions to control when the server library processes requests from client applications. 
Because only messages from the client to the server are blocked, a blocked server 
can continue to send messages to client applications. 
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A server application receives a handle when it calls the OleRegisterServer func- 


tion. 


See Also OleRegisterServer, OleUnblockServer 


OleClone 


#include <ole.h> 


OLESTATUS OleClone(/pObject, ipClient, IhClientDoc, lpszObjname, IplpObject) 


LPOLEOBJECT lpObject; /* address of object to copy 
LPOLECLIENT [pClient; | /* address of OLECLIENT for new object — 
LHCLIENTDOC [hClientDoc; /* long handle of client document > 
LPCSTR IpszObjname; /* address of string for object name 


LPOLEOBJECT FAR® IplpObject; —_/* address of pointer to new object. 


yf 

K/ 
**/ 
*/ 
**/ 


The OleClone function rriakés a copy of an 1 object. The copy 1s identical to the 


source object, but it is not connected to the server. 
Parameters IpObject | 
o Points to the object to COPY, 


_[pClient 
Points to an OLECLIEN T structure for the new y object. 


lhClientDoc 


Identifies the client document 1 in which the object is to be created. 


lpszObjname 


Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 


document and cannot contain a slash mark (/). 


[plpObject 


Points to a variable where the library will store the long pointer to the new ob- 


* ject. 


Return Value © The return value i is OLE_ OK if the function i is successful. Otherwise, it is an error 


value, which may be one of the following: 


OLE. BUSY | 
OLE_ERROR_HAN DLE 
OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


666 OleClose 


Comments 


See Also 


OleClose 


#include <ole.h> 


Client applications often use the OleClone function to support the Undo command. 


A client application can supply a new OLECLIENT structure for the cloned ob- 
ject, if required. : 


OleEqual 


OLESTATUS OleClose(/pObject) 
LPOLEOBJECT [pObject; /* address of object to close sf | 


Parameters 


Return Value 


See Also 


The OleClose function closes the specified open object. Closing an object termi- 
nates the connection with the server application. 


[pObject 
Points to the object to close. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


OleActivate, OleDelete, OleReconnect 
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OleCopyFromLink — _ | BAT 


#include <ole.h> 


OLESTATUS OleCopyFromLink([pObject, lpszProtocol, lpClient, IhClientDoc, lpszObjname, 


[plp Object) 
LPOLEOBJECT lpObject; /* address of object to embed **/ 
LPCSTR [pszProtocol; | /* address of protocol name aT 
LPOLECLIENT [pClient; — /* address of client structure */ 
LHCLIENTDOC [hClientDoc;, /* long handle of client document. = ef 
LPCSTR [pszObjname; /* address of string for object name * 
LPOLEOBJECT FAR* IplpObject; /* address of pointer to new object ai. 
The OleCopyFromLink function makes an embedded copy of a linked object. 
Parameters [pObject 
Points to the linked object that is to be embedded. 
lpszProtocol 


Return Value 


Comments 


See Also — 


Points to a null-terminated string ipaaivine the name of the protocol required 
for the new embedded object. Currently, this value can be StdFileEditing (the 
name of the ebiedt linking and eens protocol). 


[pClient — 


Points to an OLECLIENT structure for the new object. 


—ThClientDoc 


Identifies the client document in which the object is to be created. 


lpszObjname _ | 
Points to a null- terminated string specifying the client’s name for the object. 


[plpObject | 
Points to a variable where the long pointer to the new object will be stored. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_HANDLE 
OLE_ERROR_NAME 
OLE_ERROR_OBJECT 
OLE_ERROR_PROTOCOL 
OLE_WAIT -FOR_ RELEASE 


Making an embedded copy of a linked object may involve starting the server appli- 
cation. 


OleObjectConvert 
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OleCopyToClipboard : SESE 


#include <ole.h> 


OLESTATUS OleCopyToClipboard(/pObject) | 
LPOLEOBJECT [pObject; /* address of object */ 


The OleCopyToClipboard function puts the specified object on the clipboard. 


Parameters [pObject 
| Points to the object to copy to the clipboard. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be OLE_ERROR_OBJECT. | 


Comments A client application typically calls the OleCopyToClipboard function when a 
| user chooses the Copy or Cut command from the Edit menu. 


The client application should open and empty the clipboard, call the OleCopyTo- 
Clipboard function, and close the clipboard. 


OleCreate ee [31] 
#include <ole.h> 


OLESTATUS ee a ree IpClient, IpszClass, thClientDoc, lpszObjname, IplpObject, 
renderopt, cfFormat) 


LPCSTR [pszProtocol; /* address of string for protocol name */ 
LPOLECLIENT I[pClient; /* address of client structure sat 
LPCSTR IpszClass; /* address of string for classname EE 
LHCLIENTDOC [hClientDoc; /* long handle of client document */ 
LPCSTR IpszObjname; /* address of string for object name */ 
LPOLEOBJECT FAR* [plpObject; /* address of pointer to object. **/ 
OLEOPT_RENDER renderopt; /* rendering options st | 
OLECLIPFORMAT cfFormat; /* clipboard format | */ 


The OleCreate function creates an embedded object ofa specified class. The serv- 
er is opened to perform the initial editing. 


Parameters = —_—i[pszProtocol 
3 Points to a null-terminated string specifying the name of the protocol required 
for the new embedded object. Currently, this value can be ape men: (the 
name of the object linking and embedding protocol). 


Return Value 


Comments 
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ipClient 
Points to an OLECLIENT structure for the new object. 


lpszClass 
Points to a null-terminated string specifying the registered name of the class of 
~ the object to be created. 


lhClientDoc | | 
Identifies the client document in which the eByect is to be created. 


lpszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/). 


lplpObject | 
Points to a variable where the library will store the long pointer to the new ob- 
ject. 


renderopt 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value | Meaning 


olerender_draw The client calls the OleDraw function, and the library ob- 
| tains and manages presentation data. 
olerender_ format The client calls the OleGetData function to retrieve data in a 
: specific format. The library obtains and manages the data in 
the requested format, as specified by the cfFormat parameter. — 
olerender_none —__The client library does not obtain any presentation data and 
| does not draw the object. 


cfFor ormat 
Specifies the clipboard format when the renderopt parameter 1s 
olerender_ format. This clipboard format is used in a subsequent call to 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or 
-CF_BITMAP, the library manages the data and draws the object. The library 
does not support drawing for any other formats. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE ERROR HANDLE 


- OLE_ERROR_NAME > 


OLE_ERROR_PROTOCOL 


~ OLE_WAIT_FOR_RELEASE 


The olerender_ none rendering option is typically used to support hyperlinks. 
With this option, the client does not call OleDraw and calls OleGetData only for 
ObjectLink, OwnerLink, and Native formats. | | 


670 j$‘OleCreateFromClip 


The olerender_ format rendering option allows a client to compute data (instead © 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- 
trieve data in the specified format. 


The olerender_ draw rendering option is the most typical option. It is the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also exploit the flexibility that is inherent in 
this option. 


See Also OleCreateFromClip, OleCreateFromTemplate, OleDraw, OleGetData 


OleCreateFromClip — EXE 


#include <ole.h> 


OLESTATUS OleCreateFromClip(/pszProtocol, [pClient, lhClientDoc, lpszObjname, lplp Object, 
renderopt, cfFormat) 


LPCSTR IpszProtocol; /* address of string for protocol name */ 
LPOLECLIENT [pClient; /* address of client structure */ 
LHCLIENTDOC /hClientDoc; /* jong handle of client document ta: | 
LPCSTR [pszObjname; /* address of string for object name */ 
LPOLEOBJECT FAR* IplpObject; /* address of pointer to object | **/ 
~OLEOPT_RENDER renderopt; /* rendering options a 
OLECLIPFORMAT cfFormat; /* clipboard format Fi 


The OleCreateFromClip function creates an object from the clipboard. 


Parameters — lpszProtocol 

| Points to a null-terminated tang specifying the name of the protocol required 
for the new embedded object. Currently, this value can be StdFileEditing (the 
name of the object linking and embedding protocol) or Static (for uneditable 
pictures only). | 

ipCrierit 

Points to an OQLECLIENT structure allocated and initialized by the client appli- 
cation. This pointer is used to locate the callback function and is passed in call- 
back notifications. 


lhClientDoc — | 
Identifies the client document in which the object is being created. 


Return Value 


Comments 
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lpszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/). 


lplpObject 
Points to a variable where the brary will store the long pointer to the new ob- 
ject. 


renderopt 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value Meaning 


olerender_ draw The client calls the OleDraw function, and the library ob- 
tains and manages presentation data. — 

olerender_ format The client calls the OleGetData function to retrieve data in a 
specific format. The library obtains and manages the data in 
the requested format, as specified by the cfFormat parameter. 

olerender_ none The client library does not obtain any presentation data and 
does not draw the object. : 


cfFormat 
Specifies the clipboard format when the renderopt parameter is 
olerender_ format. This clipboard format is used in a subsequent call to 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or _ 
CF_BITMAP, the library manages the data and draws the object. The library 
~ does not support drawing for any other formats. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error — 
value, which may be one of the following: 


OLE_ERROR_CLIP 
OLE_ERROR_FORMAT 
OLE_ERROR_HANDLE 
OLE_ERROR_NAME 
OLE_ERROR_OPTION 
OLE_ERROR_PROTOCOL 
OLE_WAIT_FOR_RELEASE 


The client application should open and empty the clipboard, call the OleCreate- 
FromClip function, and close the clipboard. _ 


The olerender_ none rendering option is typically used to oe hyperlinks. 
With this option, the client does not call OleDraw and calls OleGetData only for 
nara OwnerLink, and Native formats. 


672 OleCreateFromFile 


See Also 


OleCreateFromFile 


#include <ole. h> 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- 
trieve data in the specified format. | | 


The olerender_ draw rendering option is the most typical option. It 1s the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to | 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also exploit the flexibility that is inherent in 
this option. 


OleCreate, OleCreateFromTemplate, OleDraw, OleGetData, 
ener Create romehp 


OLESTATUS OleCreateFromFile(/pszProtocol, [pClient, BeCiae. lpszF’ fle: IhClientDoc, 
[pszObjname, Iplp Object, renderopt, cfFormat) 


LPCSTR I[pszProtocol; /* address of string for protocol name a | 
LPOLECLIENT /[pClient; /* address of client structure */ 
LPCSTR I[pszClass; /* address of string for class name ay 
LPCSTR IpszFile; /* address of string for filename ae 
LHCLIENTDOC IhClientDoc; _/* long handle of client document | 
LPCSTR IpszObjname; /* address of string for object name __ */ 
LPOLEOBJECT FAR* [plpObject; —_—s/* address of pointer to object */ 
OLEOPT_RENDER renderopt; /* rendering options i 
OLECLIPFORMAT cfFormat; /* clipboard format a. */ 


| Parameters 


The OleCreateFromFile function creates an embedded object from the contents 
of a named file. 


[pszProtocol 
Points to a null-terminated string specifying the n name of the protocol required 
for the new embedded object. Currently, this value can be StdFiieEditing (ihe 
name of the object linking and rae aa 


IpClient | 
Points to an OLECLIENT structure allocated and initialized by the client appli- 
cation. This pointer is used to locate the callback function and is passed in call- 
back notifications. 


Return Value | 
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jasrClass 
Points to a null-terminated string specifying the name of the class for the new 
object. If this value is NULL, the library uses the extension of the filename 
pointed to by the /pszFile parameter to find the class name for the object. 


lpszFile 
Points to a null-terminated string specifying the name of the A containing the 
object. 


UhClientDoc _ 


Identifies the client document in which the object is being created. 


lpszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/). 


lplpObject 
Points to a variable where the iibrary will store the long pointer to the new ob- 
ject. 


renderopt 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value Meaning 


olerender_ draw The client calls the OleDraw function, and the library ob- 
: | tains and manages presentation data. | 
olerender_format —_ The client calls the OleGetData function to retrieve data in a 
eo specific format. The library obtains and manages the datain | 
the requested format, as specified by the cfFormat parameter. 


olerender_none _ The client library does not obtain any presentation data and 
does not draw the object. 


cfFormat 
Specifies the clipboard format Ghen the renderopt parameter is 
olerender_ format. This clipboard format is used in a subsequent call to 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or 
CF_BITMAP, the library manages the data and draws the object. The library 
does not support drawing a any other formats. 


The return value is OLE_OK if dis Aanction i iS successful. Siheiee: it is an error | 


value, which may be one of the following: 


OLE_ERROR_CLASS _ 
OLE_ERROR_HANDLE 
OLE_ERROR_MEMORY 
OLE_ERROR_NAME 


~OLE_ERROR_PROTOCOL 


OLE_WAIT_FOR_RELEASE 
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Comments 


See Also 


OleCreateFromTemplate 


#include Zole h> 


When a client application calls the OleCreateFromFile function, the server is 
started to render the Native and presentation data and then is closed. (If the server 
and document are already open, this function simply retrieves the information, 
without closing the server.) The server does not How the object to the user for 
editing. 


The olerender_ none rendering option is typically used to support hyperlinks. | 
With this option, the client does not call OleDraw and calls OleGetData only for 
ObjectLink, OwnerLink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- _ 
trieve data in the specified format. 


The olerender_ draw rendering option is the most typical option. It is the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also exploit the flexibility that is inherent in 
this option. 


If a client application accepts files dropped from File Manager, it should respond 
to the WM_DROPFILES message by calling OleCreateFromFile and specify- | 
ing Packager for the IpszClass parameter to indicate Microsoft Windows Object 
eee | 


OleCreate, OleCreateFromTemplate, OleDraw, OleGetData 


OLESTATUS OleCreateFromTemplate(/pszProtocol, IpClient, lpszTemplate, lhClientDoc, 
lpszObjname, lplpObject, renderopt, cfFormat) 


LPCSTR IpszProtocol; /* address of string for protocol name e) 
LPOLECLIENT /pClient; /* address of client structure aed) 
LPCSTR IpszTemplate; /* address of string for path of file */ 
LHCLIENTDOC [hClientDoc; | /* long handle of client document ‘| 
LPCSTR IpszObjname; /* address of string for object name */ 
LPOLEOBJECT FAR* IplpObject; /* address of pointer to object Hf 
OLEOPT_RENDER renderopt; ——_—sS/* rendering options ee | 


OLECLIPFORMAT cfFormat; /* clipboard format | ee | 
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The OleCreateFromTemplate function creates an object by using another object 
as a template. The server is opened to perform the initial editing. 


Parameters lpszProtocol | | 
Points to a null-terminated string specifying the name of the protocol required 
for the new embedded object. Currently, this value can be StdFileEditing (the 
name of the object linking and embedding protocol). 


lpClient 
Points to an OLECLIENT structure for the new 0b) ect. 


lpszTemplate 
Points to a null-terminated string specifying the path of the file to be used as a 
template for the new object. The server is opened for editing and loads the ini- 
tial state of the new object from the named template file. 


ThClientDoc 
Identifies the client document in which the object is being created. 


lpszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/). 


lplpObject 
Points to a variable where the library will store the long pointer to the new ob- 
ject... | 


renderopt . 7 : 
Specifies the client’ S preference for presetitation data for the object. This pa- 
rameter can be one of the following values: 


Value _ Meaning 


_olerender_ draw The client calls the OleDraw function, and the library ob- 
| tains and manages presentation data. | 
olerender_ format The client calls the OleGetData function to retrieve data ina 
specific format. The library obtains and manages the datain _ 
the requested format, as specified by the cfFormat parameter. — 


olerender_none The client library does not obtain any presentation data = 
does not draw the object. : 


cfFormat 
Specifies the clipboard format when the renderopt parameter is 
olerender_ format. This clipboard format is used in a subsequent call tothe 
OleGetData function. If this clipboard format is CF_METAFILEPICT, | 
CF_DIB, or CF_BITMAP, the library manages the data and draws the object. 
The library does not support drawing for any other oe | 
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Return Value 


Comments 


See Also | 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: ) 


OLE_ERROR_CLASS 
OLE_ERROR_HANDLE 
OLE_ERROR_MEMORY 
OLE_ERROR_NAME 
OLE_ERROR_PROTOCOL 
OLE_WAIT_FOR_RELEASE 


The client library uses the filename extension of the file specified in the 
[pszTemplate parameter to identify the server for the object. The association 
between the extension and the server is stored in the registration database. 


The olerender_none rendering option is typically used to support hyperlinks. 
With this option, the client does not call OleDraw and calls OleGetData only for 
ObjectLink, OwnerLink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- 
trieve data in the specified format. 


The olerender_ draw rendering option is the most typical option. It is the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also exploit the flexibility that is inherent in 
this option. 


OleCreate, OleCreateFromClip, OleDraw, OleGetData, OleObjectConvert 
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OleCreatelnvisible a EXE 


#include <ole.h> 


OLESTATUS OleCreatelInvisible(/pszProtocol, lpClient, IpszClass, lhClientDoc, IpszObjname, 
lplpObject, renderopt, cfFormat, fActivate) : 


LPCSTR /pszProtocol; /* address of string for protocol name ‘| 
LPOLECLIENT /pClient; — /* address of client structure **/ 
LPCSTR /pszClass; /* address of string for classname *} 
LHCLIENTDOC /[hClientDoc; /* long handle of client document ef 
LPCSTR /pszObjname; /* address of string for object name **/ 
LPOLEOBJECT FAR® /plpObject; /* address of pointer to object — si | 
OLEOPT_ RENDER renderopt; /* rendering options aa 
OLECLIPFORMAT cfFormat; /* clipboard format 7 =), 
BOOL fActivate; /* server activation flag Yak =) 


The OleCreateInvisible function creates an object without displaying the server 
application to the user. The function either starts the server to create the object or 
creates a blank object of the specified class and format without starting the server. 


Parameters lpszProtocol 
| ~ Points to a null-terminated string specifying the name of the protocol required — 
- for the new embedded object. Currently, this value can be StdFileEditing (the — 
name of the object linking and embedding Polen or Static (for uneditable 
pictures only). | 


lpClient | | i 
Points to an OLECLIENT structure allocated and initialized by the client appli- 
cation. This pointer is used to locate the callback function and is passed in call- 
back notifications. ) 


lpszClass 
Points to a null-terminated string specifying the registered name of the class of 
the object to be created. | 


lhClientDoc | 
Identifies the client document in which the object is being created. 


lpszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any oe objects in the 
document and cannot contain a slash mark (/). 


lplp Object 
Points to a variable where the library will store the long pointer to the new ob- 
ject. | | 


renderopt 
Specifies the client’s preference for presentation data for the object.’ This pa- 
rameter can be one of the ee values: - 
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Return Value 


Comments 


See Also 


Value Meaning 


olerender_ draw The client calls the OleDraw function, and the library ob- 
tains and manages presentation data. 
olerender_ format The client calls the OleGetData function to retrieve data in a 
specific format. The library obtains and manages the data in 
| the requested format, as specified by the cfFormat parameter. 
olerender_none The client library does not obtain any presentation data and 
does not draw the object. 


cfFormat 
Specifies the clipboard format when the renderopt paranete 1S 
olerender_format. This clipboard format is used in a subsequent call to 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or 
CF_BITMAP, the library manages the data and draws the object. The library 
does not support drawing for any other formats. 


fActivate 
Specifies whether to start the server for the object. If this parameter is TRUE 
the server is started (but not shown). If this parameter is FALSE, the server is 
not started and the function creates a blank object of the specified class and for- 
mat. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_ HANDLE 
OLE_ERROR NAME | 
OLE_ERROR PROTOCOL 


An application can avoid redrawing an object repeatedly by calling the 
OleCreatelInvisible function before using such functions as OleSetBounds, 
OleSetColorScheme, and OleSetTargetDevice to set up the object. After setting 
up the object, the application can either call the OleActivate function to display 
the object or call the OleUpdate and OleClose functions to update the object 
without displaying it. . 


OleActivate, OleClose, OleSetBounds, OleSetColorScheme, 
OleSetTargetDevice, OleUpdate 
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OleCreateLinkFromClip _ Ex 
#include <ole.h> 


OLESTATUS OleCreateLinkFromClip(/pszProtocol, [pClient, lhClientDoc, [pszObjname, IplpObject, 
renderopt, cfFormat) 


LPCSTR I[pszProtocol; /* address of string for protocol name a 
LPOLECLIENT [pClient; /* address of client structure eer.) | 
LHCLIENTDOC [hClientDoc; /* long handle of client document — */ 
LPCSTR IpszObjname; /* address of string for object name */ 
LPOLEOBJECT FAR* [plpObject; /* address of pointer to object oS oF 
OLEOPT_RENDER renderopt; /* rendering options ef 
OLECLIPFORMAT cfFormat; /* clipboard format */ 
The OleCreateLinkFromClip function typically creates a link to an object from | 
the clipboard. 
Parameters lpszProtocol 


Points to a null-terminated string specifying the name of the required protocol. 
Currently, this value can be StdFileEditing ae name of the object linking and 
embedding ee 


[pClient 
Points to an OLECLIENT structure allocated and initialized by the client appli- 
_ cation. This pointer is used to locate the callback function and is passed in call- 
back notifications. 


lhClientDoc 
Identifies the client document 1 in which the object is being created. 


lpszObjname 
Points to a null-terminated string specifying the client’ s name for the object. — 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/). 


IplpObject 
Points to a variable where the library will store the long pointer to the new ob- 
ject. 


-_ renderopt 
Specifies the client’ s preference for presentation data for the object. This pa- 
- rameter can be one of the following values: : 


Value _ Meaning 
olerender_ draw The client calls the OleDraw function, and the library ob- 
2 tains and manages presentation data. 


olerender_format — The client calls the OleGetData function to retrieve data in a 
| specific format. The library obtains and manages the data in 
the requested format, as specified by the cfFormat parameter. 
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Return Value 


Comments 


See Also 


Value Meaning 


olerender_none The client library does not obtain any presentation data and 
does not draw the object. 


cfFormat 
Specifies the clipboard format when the renderopt parameter is 
olerender_format. This clipboard format is used in a subsequent callto 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or 
CF_BITMAP, the library manages the data and draws the object. The library 
does not support drawing for any other formats. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_CLIP 
OLE_ERROR_FORMAT 
OLE_ERROR_HANDLE 
OLE_ERROR_NAME 
OLE_ERROR_PROTOCOL 
OLE_WAIT_FOR_RELEASE 


The olerender_none rendering option is typically used to support hyperlinks. 
With this option, the client does not call the OleDraw function and calls OleGet- 
Data only for ObjectLink, OwnerLink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- 
trieve data in the specified format. 


The olerender_ draw rendering option is the most typical option. It is the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also et the flexibility that is inherent in 
this option. 


OleCreate, OleCreateFromTemplate, OleDraw, OleGetData, 
OleQueryLinkFromClip 
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OleCreateLinkFromFile a 
#include <ole.h> | | 


OLESTATUS OleCreateLinkFromFile(/pszProtocol, IpClient, lpszClass, lpszFile, lpszItem, 
[hClientDoc, IlpszObjname, lplpObject, renderopt, cfFormat) 


LPCSTR I[pszProtocol; /* address of string for protocol name i) 
LPOLECLIENT [pClient; | /* address of client structure **/ 
LPCSTR [pszClass; /* string for class name ay 
LPCSTR I[pszFile; /* address of string for filename =f 
LPCSTR Ipszltem; /* address of string for document part to link */ 
LHCLIENTDOC [hClientDoc; /* long handle of client document 7 
LPCSTR /pszObjname; /* address of string for object name | */ 
LPOLEOBJECT FAR?® IpipObject; /* address of pointer to new object sy 
OLEOPT_RENDER renderopt; /* rendering options a | 
OLECLIPFORMAT cfFormat; — /* clipboard format si 


The OleCreateLinkFromFile function creates a linked object from a file that con- 
tains an object. If necessary, the library starts the server to render the presentation 
data, but the object is not shown in the server for editing. 


Parameters baie oH ; 
Points to a null-terminated string specifying the name of the required protocol. _ 
Currently, this value can be rr ae (the name of the pie! linking and 
embedding protocol). 


l[pClient 
Points to an OLECLIENT structure allocated and initialized by the client appli- 
cation. This pointer is used to locate the callback function and i is passed in call- 
back notifications. 


lpszClass 
Points to a null-terminated string specifying the name of the class for the new 
object. If this value is NULL, the library uses the extension of the filename 
pointed to by the /pszFile parameter to find the class name for the object. — 


lpszFile 
Points to a null-terminated string specifying the name of the file containing the 
object. 

lpszItem 
Points to a null-terminated string identifyitig the part of the document to link to. 
If this value is NULL, the link is to the entire document. . 


[hClientDoc 
Identifies the client document 1 in which the object is being created. 
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Return Value 


Comments 


[pszObjname 
Points to a null-terminated string specifying the client’s name for the object. 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark : ). 


[plpObject 
Points to a variable where the library will store the long pointes to the new ob- 
ject. | 


renderopt 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value Meaning 


olerender_draw The client calls the OleDraw function, and the eee ob- 
tains and manages presentation data. 

olerender_ format The client calls the OleGetData function to retrieve data in a 
specific format. The library obtains and manages the data in 
the requested format, as specified by the cfFormat parameter. 

olerender_none The client library does not obtain any presentation data and 
does not draw the object. 


cfFormat 
Specifies the clipboard format when the renderopt parameter is 
olerender_ format. This clipboard format is used in a subsequent call to 
OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or 
CF_BITMAP, the library manages the data and draws the object. The library 
does not support drawing for any other formats. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_CLASS 
OLE_ERROR_HANDLE 
OLE_ERROR_MEMORY 
OLE_ERROR_NAME 
OLE_ERROR_PROTOCOL 
OLE_WAIT_FOR_RELEASE 


The olerender_ none rendering option is typically used to support hyperlinks. 


With this option, the client does not call OleDraw and calls OleGetData only for 
ObiectLink, Ownerl ink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls OleGetData to re- 
trieve data in the specified format. 


See Also 


OleDelete 


#include <ole.h> 
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The olerender_ draw rendering option is the most typical option. It is the easiest 
rendering option for the client to implement (the client simply calls OleDraw), 
and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and embedding (OLE) may also exploit the flexibility that is inherent 1 in 
this option. 


OleCreate, OleCreateFromFile, OleCreateFromTemplate, OleDraw, 
OleGetData 


OLESTATUS OleDelete(/pObject) 
LPOLEOBJECT [pObject; /* address of object to delete a 


Parameters 


Return Value 


Comments 


See Also 


The OleDelete function deletes an object and frees memory that was associated 
with that object. If the object was open, it is closed. 


pObject 


Points to the object to delete. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


~ OLE_BUSY 


OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


An application uses the acre function when ths object is no ieieee part of 


the client document. 


The OleDelete function, unlike OleRelease, indicates that the ee has been per- 


manently removed. 


OleClose, OleRelease 
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OleDraw 


#include <ole.h> 


OLESTATUS OleDraw(/pObject, hdc, lprcBounds, lprcWBounds, hdcFormat) 


LPOLEOBJECT I[pObject; /* address of object to draw if 
HDC hdc; | /* handle of DC for drawing object * | 
const RECT FAR® IprcBounds; /* bounding rectangle for drawing object **/ 
const RECT FAR®* [prcWBounds; /* bounding rectangle for metafile DC *f 
HDC hdcFormat; /* handle of DC for formatting object 7 a 


Parameters 


Return Value 


Comments 


The OleDraw function draws a specified object into a bounding rectangle in a 
device context. 


[pObject 
Points to the object to draw. 


hdc 
Identifies the device context in which to draw the object. 


[prcBounds 


Points to a RECT structure defining the bounding rectangle, in logical units for 
the device context specified by the hdc parameter, in which to draw the object. 


IprcWBounds 
Points to a RECT structure defining the bounding rectangle if the hdc parame- 
ter specifies a metafile. The left and top members of the RECT structure 
should specify the window origin, and the right and bottom members should 
specify the window extents. 


hdcFormat 
Identifies a device context describing the target device for anieh to format the 
object. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_ABORT 
OLE_ERROR_BLANK 
OLE_ERROR_DRAW 
OLE_ERROR_MEMORY | 
OLE_ERROR_OBJECT 


This function returns OLE_ ERROR _ ABORT if the callback function returns 
FALSE during drawing. 


When the hdc parameter specifies a metafile device ai the rectangle 
specified by the IprcWBounds parameter contains the rectangle specified by the 


See Also 


OleEnumFormats 


_ #include <ole.h> 
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lprcBounds parameter. If hdc does not specify a metafile evict context, the 
ipreWBounds parameter is ignored. 


The library may use an object handler to render the object, and this object handler 
may need information about the target device. Therefore, the device-context 
handle specified by the hdcFormat parameter is required. The /prcBounds parame- 
ter identifies the rectangle on the device context (relative to its current mapping 
mode) that the object should be mapped onto. This may involve scaling the picture 
and can be used by client applications to impose a view scaling between the dis- 
played view and the final printed image. 


An object handler should format an object as if it were to be drawn at the size 
specified by a call to the OleSetBounds function for the device context specified 
by the hdcFormat parameter. Often this formatting will already have been done by 
the server application; in this case, the library simply renders the presentation data 
with suitable scaling for the required bounding rectangle. If cropping or banding is 
required, the device context in which the object is drawn may include a chipping re- 
gion smaller than the specified bounding rectangle. 


OleSetBounds 


~ OLECLIPFORMAT OleEnumFormats(/pObject, cfFormat) 
LPOLEOBJECT [pObject; /* address of object to query **/ 
OLECLIPFORMAT cfFormat; /* format from previous function call sa 


Parameters 


Return Value 


Comments 


The OleEnumFormats function enumerates the data formats that describe a 
specified object. 


lpObject 
Points to the object to be queried. 

cfFormat 
Specifies the format returned by the last call to the OleEnumFormats function. 
For the first call to this function, this parameter is zero. 


The return value is the next available format if any further formats are available. 


Otherwise, the return value is NULL. 


When an application specifies NULL for the cfFormat parameter, the OleEnum- 


- Formats function returns the first available format. Whenever an application 
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specifies a format that was returned by a previous call to OleEnumFormats, the 
function returns the next available format, in sequence. When no more formats are 
available, the function returns NULL. 


See Also OleGetData | 


OleEnumObjects 


#include <ole.h> 


OLESTATUS OleEnumObjects(/hDoc, IplpObject) 
LHCLIENTDOC [hDoc; /* document handle */ 
LPOLEOBJECT FAR* IplpObject; /* address of pointer to object */ 


The OleEnumObjects function enumerates the objects in a specified document. 


Parameters IhDoc 
Identifies the document for which the objects are enumerated. 


[plp Object 7 
Points to an object in the document when the function returns. For the first call 
to this function, this parameter should point to a NULL object. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: | 


OLE_ERROR_HANDLE 
OLE_ERROR_OBJECT 


Comments : When an application specifies a NULL object for the [plpObject parameter, the 
OleEnumObjects function returns the first object in the document. Whenever 
an application specifies an object that was returned by a previous call to 

~ OleEnumObjects, the function returns the next object, in sequence. When there 
are no more objects in the document, the /plpObject parameter points to a NULL 
object. 


Only objects that have been loaded and not released are enumerated by this func- 
tion. | oe 


See Also OleDelete, OleRelease 
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OleEqual | | 34] 
#include oles | 


OLESTATUS OleEqual(/pObject1, lpObject2) 
LPOLEOBJECT [pObject1; /* address of first object to compare **/ 
LPOLEOBJECT [pObject2; /* address of second object to compare **/ 


The OleEqual function compares two objects for equality. 


Parameters lpObjectl 
Points to the first object to test for equality. 


lpObject2 
Points to the second object to test for equality. 


Return Value — The return value is OLE_OK if the specified objects are equal. Otherwise, it is an 
error value, which may be one of the following: 


OLE_ERROR_OBJECT 
OLE_ERROR_NOT_EQUAL 


Comments - _ Embedded objects are equal if their class, item, and native data are identical. 
Linked objects are equal if their class, document, and item are identical. 


See Also OleClone, OleQueryOutOfDate 


OleExecute ott i 
#include Siens 7 | ote 


OLESTATUS OleExecute(lpObject, hglbCmds, reserved) 


LPOLEOBJECT [pObject; —_‘/* address of object receiving DDE commands **/ 
HGLOBAL hglbCmads; _ /* handle of memory with commands 2 | 
UINT reserved; /* reserved ey 


The OleExecute function sends dynamic data exchange (DDE) execute com- 
mands to the server for the specified object. | 


Parameters [pObject | | 
Points to an object identifying the server to which DDE execute commands 


are sent. 
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hglbCmds 
Identifies the memory containing one or more DDE execute commands. 


reserved “ 
Reserved; must be zero. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_COMMAND 
OLE_ERROR_MEMORY 
OLE_ERROR_NOT_OPEN 
OLE_ERROR_OBJECT 
OLE_ERROR_PROTOCOL 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


Comments _ The client application should call the OleQueryProtocol function, specifying 
| StdExecute, before calling the OleExecute function. The OleQueryProtocol func- 
tion succeeds if the server for an object supports the OleExecute function. 


See Also OleQueryProtocol 


OleGetData Ba 
#include <ole.h> 


OLESTATUS OleGetData(/pObject, cfFormat, lphData) 


LPOLEOBJECT pObject; /* address of object to query | | 
~OQLECLIPFORMAT cfFormat; /* format for retrieved data sf | 
HANDLE FAR?® [phData; /* address of memory to contain data | 


The OleGetData function retrieves data in the requested format from the specified 
object and supplies the handle of a memory or graphics device interface (GDI) ob- 
ject containing the data. 


Faraineiers ipOojeci | 
Points to the object from which data is retrieved. 
_cfFormat + ota? 
Specifies the format in which data is returned. This parameter can be one of the 
predefined clipboard formats or the value returned by the RegisterClipboard- 
Format function. : | 


Return Value 


Comments 


See Also 


OleGetLinkUpdateOptions 


#include <ole.h> 
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lphData 
Points to the handle of a memory object that contains the data when the func- 
tion returns. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_BLANK 
OLE_ERROR_FORMAT 
OLE_ERROR_OBJECT 
OLE_WARN_DELETE_DATA | 


If the OleGetData function returns OLE_WARN_DELETE_DATA, the client ap- 
plication owns the data and should free the memory associated with the data when 

the client has finished using it. For other return values, the client should not free | 

the memory or modify the data, because the data is controlled by the client library. 
If the application needs the data for long-term use, it should copy the data. 


The OleGetData function typically returns OLE_WARN_DELETE_DATA if an 
object handler generates data for an object that the client library cannot interpret. 
In this case, the client application is responsible for controlling that data. © 


When the OleGetData function specifies CF_METAFILE or CF_BITMAP, the 
[phData parameter points to a GDI object, not a memory object, when the function 
returns. OleGetData supplies the handle of a memory object for all other formats. 


OleEnumFormats, OleSetData, RegisterClipboardFormat | 


OLESTATUS OleGetLinkUpdateOptions(/pObject, lp UpdateOpt) 
LPOLEOBJECT /pObject; _ /* address of object to query © */ 
~OLEOPT_UPDATE FAR? IpUpdateOpt; /* address of update options */ 


Parameters 


The OleGetLink UpdateOptions function retrieves the link-update epucns for the 
presentation of a specified object. 


lpObject 
Points to the object to query. 
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[pUpdateOpt 
Points to a variable in which the function stores the current value of the link- 
update option for the specified object. The link-update option setting may be 
one of the following values: 


Value Meaning 


oleupdate_always Update the linked object whenever possible. This option sup- 
ports the Automatic link-update radio button in the Links 
dialog box. 


oleupdate_oncall Update the linked object only on request from the client ap- 
plication. This option supports the Manual link-update radio 
button in the Links dialog box. 


oleupdate_onsave Update the linked object when the source document is saved — 
by the server. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 


See Also OleSetLinkUpdateOptions 


OlelsDcMeta En 
#include <ole.h> 


BOOL OleIsDcMeta(hdc) 
HDC hdc; /* device-context handle a | 


The OleIsDcMeta function determines whether the specified device context is a 
metafile device context. | 


Parameters hdc 
Identifies the device context to query. - 
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OleLoadFromStream a Ex 
#include <ole.h> 


OLESTATUS OleLoadFromStream(ipStream, lpszProtocol, lpClient, thClientDoc, lpszObjname, 
lplpObject) 

LPOLESTREAM IpStream; /* address of stream for object **/ 

~ LPCSTR IpszProtocol; _ _ /* address of string for protocol name af 
LPOLECLIENT /pClient; /* address of client structure a) 

LHCLIENTDOC [hClientDoc; /* long handle of client document =} 

LPCSTR IpszObjname; — /* address of string for objectname _ **/ 

LPOLEOBJECT FAR* IplpObject; /* address of pointer to object ef 


The OleLoadFromStream function loads an object from the containing document. 


Parameters [pStream 
Points to an OLESTREAM structure that was allocated and initialized by the 
client application. The library calls the Get function in the 
OLESTREAMVTBL structure to obtain the data for the object. 


lpszProtocol 
Points to a null-terminated string specifying the name of the required protocol. 
Currently, this value can be StdFileEditing (the name of the object linking and : 
embedding protocol) or Static uneditable aera only). | 


[pClient oh 
Points to an OLECLIENT structure allocated and initialized by the client appli- 
cation. This pointer is used to locate the callback function and is passed i in call- 
back notifications. 


lhClientDoc 
Identifies the client document in which the object is ee eaied 


lpszObjname | : 
Points to a null-terminated string specifying the client’s name for the object | 


lplpObject 
Points to a variable in which the library stores a pointer to the loaded onlert 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
| | value, which may be one of the following: | | 


_ OLE_ERROR_HANDLE 
- OLE_ERROR_NAME 
OLE_ERROR_PROTOCOL 
- OLE_ERROR_STREAM | 
- OLE_WAIT_FOR_RELEASE 
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Comments 


See Also 


OleLockServer 


#include <ole.h> 


To load an object, the client application needs only the location of that object in a 
file. A client typically loads an object only when the object is nes (for ex- 
ample, when it must be displayed). 


If an object cannot be loaded when the /pszProtocol parameter specifies 
StdFileEditing, the application can call the OleLoadFromStream function again, 
specifying Static. 


If the object is linked and 1 the server and document are open, the library automat- 
ically makes the link between the client and server applications when an applica- 
tion calls OleLoadFromStream. 


OleQuerySize, OleSaveToStream 


OLESTATUS OleLockServer(/pObject, IphServer) 
LPOLEOBJECT IpObject; /* address of object i 
iia aari FAR* IphServer; /* address of handle of server a 


Parameters 


Return Value 


Comments 


The OleLockServer function is called by a client application to keep an open serv- 
er application in memory. Keeping the server application in memory allows the 
client library to use the server application to open objects quickly. 


[pObject 
Points to an object the client library uses to identify the open server application 
to keep in memory. When the server has been a this object can be deleted. 


IphServer 


_ Points to the handle of the server application when the function returns. 


The return value is OLE_OK if the function is successful. Otherwise, it 1s an error 
value, which may be one of the following: 


OLE_ERROR_COMM 


OLE_EKRRKOR_LAUNCH 
OLE_ERROR_OBJECT 


A client calls OleLockServer to speed the opening of objects when the same serv- 
er is used for a number of different objects. Before the client terminates, it must 
call the OleUnlockServer function to release the server from memory. 


See Also 


OleObjectConvert 


#include <ole.h> 
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When OleLockServer is called more than once for a given server, even by differ- 
ent client applications, the server’s lock count is increased. Each call to Ole- 
UnlockServer decrements the lock count. The server remains locked until the 
lock count is zero. If the object identified by the [pObject parameter is deleted 
before calling the OleUnlockServer function, OleUnlockServer must still be 
called to decrement the lock count. 


If necessary, a server can terminate even though a client has called the OleLock- 
Server function. 


OleUnlockServer 


~OLESTATUS OleObjectConvert(/pObdject, lpszProtocol, lpClient, IhClientDoc, ipszObjname, 


[plpObject) 

LPOLEOBJECT [pObject; _ /* address of object to convert */ 

LPCSTR IpszProtocol; /* address of string for protocol name */ 

LPOLECLIENT [pClient; /* address of client for new object — #] 

LHCLIENTDOC [hClientDoc; /* long handle of client document */ 

-LPCSTR [pszObjname; /* address of string for object name By ae 

LPOLEOBJECT FAR* IplpObject; /* address of pointer to new object i 
The OleObjectConvert function creates a new object that supports a specified 
protocol by converting an existing object. This function neither deletes nor re- 
places the original object. 

Parameters lpObject 


Points to the object to convert. 


[pszProtocol 
Points to a null-terminated string specifying the name of the required protocol. — 
Currently this value can be Static (for uneditable pcs only). 


[pClient — 
Points to an OLECLIEN T structure for the new object. 


IhClientDoc — 


Identifies the client document in which the eae 1S being created. 


lpszObjname | | 
Points to a null- terminated string specifying the client’s name for the object. | 
This name must be unique with respect to the names of any other objects in the 
document and cannot contain a slash mark (/ )3 
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Return Value 


Comments 


See Also 


—OleQueryBounds 


#include <ole.h> 


lplpObject 
Points to a variable in which the library stores a pointer to the new object. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_HANDLE 
OLE_ERROR_NAME 
OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 


The only conversion currently supported is that of changing a linked or embedded 
object to a static object. 


OleClone 


OLESTATUS OleQueryBounds(/pObject, lpBounds) 
LPOLEOBJECT [pObject; —_—‘/* address of object to query i 
RECT FAR® /pBounds; _ /* address of structure for bounding case | 


Parameters 


The OleQueryBounds function retrieves the extents of the bounding rectangle on 
the target device for the specified object. The coordinates are in MM_HIMETRIC 
units. 


[pObject 
Points to the object to query. 
[pBounds 


Points to a RECT structure for the extents of the bounding rectangle. The mem- 
bers of the RECT structure have the following meanings: 


Member Meaning 
rect.left 0 
rect.top 0 
‘rect.right x-extent 


rect.bottom —_y-extent 
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Return Value ~The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_BLANK 
OLE_ERROR_MEMORY 
OLE_ERROR_OBJECT 


See Also ~ OleSetBounds, SetMapMode 


OleQueryClientVersion a [3.1] 
#include <ole.h> 


DWORD OleQueryClientVersion(void) — 


The OleQueryClientVersion function retrieves the version number of the client — 


library. 
Parameters This function has no parameters. 
Return Value The return value is a doubleword value. The major version number is in the low- o 


order byte of the low-order word, and the minor version number is in the hgh: 
order byte of the low-order word. The high-order word is reserved. 


See Also OleQueryServerVersion 


OleQueryCreateFromClip Ce ong 
#include <ole.h> | ‘ 


OLESTATUS OleQueryCreateFromClip(IpszProtocol, renderopt, CfF ormat) 


LPCSTR I[pszProtocol; * /* address of string for protocol nam ik 
OLEOPT_RENDER renderopt; /* rendering options ee, */ 


OLECLIPFORMAT fF ormat; /* format for clipboard data ie =]. 


~ The OleQueryCreateFromClip function checks whether the object on the clip: 
| board supports the specified protocol and rendering options. | 
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Parameters 


Return Value 


Comments 


lpszProtocol | 
Points to a null-terminated string specifying the name of the protocol needed by 
the client. Currently, this value can be StdFileEditing (the name of the object 
linking and embedding protocol) or Static (for uneditable pictures only). 


renderopt 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value Meaning 


olerender_draw The client calls the OleDraw function, and the library ob- 
| tains and manages presentation data. _ 
olerender_ format The library obtains and manages the data in the requested for- 
mat, as specified by the cfFormat parameter. 
olerender_none The client library does not obtain any presentation data and | 
does not draw the object. 


cfFormat 
Specifies the clipboard format. This parameter is used only when the renderopt 
parameter is olerender_format. If the clipboard format is 
CF_METAFILEPICT, CF_DIB, or CF_BITMAP, the library manages the data 
and draws the object. The library does not support drawing for any other for- 
mats. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_FORMAT 
OLE_ERROR_PROTOCOL 


The OleQueryCreateFromClip function is typically used to check whether to 


enable a Paste command. 


The olerender_none rendering option is typically used to support hyperlinks. 
With this option, the client does not call OleDraw and calls the OleGetData func- 
tion only for Obj ectLink, OwnerLink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 


_ this option the client does not call OleDraw. The client calls OleGetData to re- 


trieve data in the snecified format. 


The olerender_ draw eraeine option is the most typical option. It is the easiest 


- rendering option for the client to implement (the client simply calls OleDraw), 


and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
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linking and embedding (OLE) may also exploit the flexibility that is inherent in 
this option. 


See Also OleCreateFromClip, OleDraw, OleGetData 


OleQueryLinkFromClip [Ba] 


#include <ole.h> 


OLESTATUS OleQueryLinkFromClip(/pszProtocol, renderopt, cfFormat) 


LPCSTR I[pszProtocol; /* address of string for protocolname —=_ */ 
OLEOPT_RENDER renderopt; /* rendering options of 
OLECLIPFORMAT cfFormat; /* format for clipboard data | | 


The OleQueryLinkFromClip function checks whether a client application can 
use the data on the clipboard to produce a linked object that supports the specified 
protocol and rendering options. | 


Parameters IpszProtocol 
Points to a null-terminated string specifying the name of the protocol needed By 
the client. Currently this value can be merous (the name of the object — 
linking and embedding protocol). 


renderopt | 
Specifies the client’s preference for presentation data for the object. This pa- 
rameter can be one of the following values: 


Value Meaning 


olerender_ draw The client calls the OleDraw function, and the library ob- 
tains and manages presentation data. 
olerender_ format The library obtains and manages the data in the requested for- _ 
mat, as specified by the cfFormat parameter. 


olerender_none The client library does not obtain any presentation data ae 
does not draw the object. 


cfFormat | | 
Specifies the clipboard format. This parameter is used only when the 
renderopt parameter is olerender_format. If this clipboard format is 
CF_METAFILEPICT, CF_DIB, or CF_BITMAP, the library manages the data 
and draws the object. The library does not support drawing for any other — 
formats. 


698 OleQueryName 7 


Return Value 


Comments 


See Also 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_FORMAT 
OLE_ERROR_PROTOCOL 


The OleQueryLinkFromClip function is typically used to check whether to 
enable a Paste Link command. 


The olerender_none rendering option is typically used to support hyperlinks. 
With this option, the client does not call OleDraw and calls the OleGetData func- 
tion only for ObjectLink, OwnerLink, and Native formats. 


The olerender_ format rendering option allows a client to compute data (instead 
of painting it), use an unusual data format, or modify a standard data format. With 
this option, the client does not call OleDraw. The client calls eens to re- 
trieve data in the specified format. 


The olerender_ draw rendering option is the most typical option. It is the easiest _ 
rendering option for the client to implement (the client simply calls OleDraw), 

and it allows the most flexibility. An object handler can exploit this flexibility to 
store no presentation data, a private presentation data format, or several different 
formats that it can choose among dynamically. Future implementations of object 
linking and Sone (OLE) may also open the flexibility that is inherent i in 
this option. 


OleCreateLinkFromClip, OleDraw, OleGetData 


OleQueryName 


#include <ole.h> 


OLESTATUS OleQueryName(/pODject, [pszObject, lpwBuffSize) 
LPOLEOBJECT [pObject; /* address of object a | 


LPSTR [pszObject; 


/* address of string for object name lf 


— UINT FAR®* IpwBuffSize; | /* address of word for size of buffer *) 


Parameters 


[pObject 
Points to the object whose name is being queried. 


Return Value 


See Also 


OleQueryOpen 


#include <ole.h> 
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lpszObject 
Points to a character array that contains a null-terminated string. When the func- 
tion returns, this string specifies the name of the object. 

lpwBuffSize 
Points to a variable containing the size, in bytes, of the buffer pointed to by the 
lpszObject parameter. When the function returns, this value is the number of 
bytes copied to the buffer. 


The return value is OLE_ OK if the function is successful. Otherwise, it is an error 
value, which may be OLE_LERROR_OBJECT. © 


OleRename 


OLESTATUS OleQueryOpen(ipObject) 
LPOLEOBJECT [pObject; —/* address of Sbjeckte to query st i 


Parameters 


Return Value 


See Also 


The OleQueryOpen function checks whether the specified object is open. 


[pObject 
Points to the object to query. 


The return value is OLE_OK if the object is open. Otherwise, it is an error value, 
which may be one of the following: 


OLE_ERROR_COMM 


~OLE_ERROR_OBJECT 


OLE_ERROR_STATIC 


OleActivate 
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OleQueryOutOfDate _ 
#include <ole.h> | | | 7 


OLESTATUS OleQueryOutOfDate(/pObject) | 
LPOLEOBJECT IpObject; —‘/* address of object to query st 


The OleQueryOutOfDate function checks whether an object is out-of-date. 


Parameters [pObject 
Points to the object to query. 


Return Value The return value is OLE_OK if the object is up-to-date. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_OBJECT 
OLE_ERROR_OUTOFDATE 


- Comments The OleQueryOutOfDate function has not been implemented for the current ver- 
sion of object linking and embedding (OLE). For linked objects, a a 
Date always returns OLE_OK. 


A linked object might be out-of-date if the document that is the source for the link 


has been updated. An embedded object that contains links to other objects might 
also be out-of-date. 


See Also OleEqual, OleUpdate 


OleQueryProtocol (34) 


#include <ole.h> 


void FAR* OleQueryProtocol(/pobj, lpszProtocol) 8 
LPOLEOBJECT Ipobj; — /* address of object to query oF 


LPCSTR IpszProtocol; /* address of string for protocol to query */ 
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protocol. 


Parameters Ipobj 
Points to the object to query. 


Return Value 


Comments 


See Also 


OleQueryReleaseError 


#include <ole.h> 
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lpszProtocol 
Points to a null-terminated string specifying the name of the requested protocol. 
This value can be StdFileEditing or StdExecute. | 


The return value is a void pointer to an OLEOBJECT structure if the function is 
successful, or it is NULL if the object does not support the requested protocol. The 
library can return OLE_WAIT_FOR_RELEASE when an application calls this 
function. 


The OleQueryProtocol function queries whether the specified protocol is sup- 
ported and returns a modified object pointer that allows access to the function 
table for the protocol. This modified object pointer points to a structure that has 
the same form as the OLEOBJECT structure; the new structure also points to a 
table of functions and may contain additional state information. The new pointer 
does not point to a different object—if the object is deleted, secondary pointers be- 
come invalid. If a protocol includes delete functions, ane a delete function in- 
validates all pointers to that object. 


A client application typically calls OleQueryProtocol, specifying StdExecute for 
the lpszProtocol parameter, before calling the OleExecute function. This allows 
the client application to check whether the server for an object supports dynamic 
data exchange (DDE) execute commands. 


OleExecute 


OLESTATUS OleQueryReleaseError(/pobj) 
LPOLEOBJECT Ipobj; /* address of object to query. */ 


Parameters 


Return Value 


The OleQueryReleaseError function checks the error value for an 1 asynchronous 
Operation on an Object 


lpobj — 
Points to an object for which the error value is to be queried. 


The return value, if the function is successful, is either OLE_OK if the asynchro- 
nous operation completed successfully or the error value for that operation. If the 


- pointer passed in the Ipobj parameter is invalid, the function returns 


OLE_ERROR_OBJECT. 
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Comments A client application receives the OLE_RELEASE notification when an asynchro- 
nous operation has terminated. The client should then call OleQueryRelease- 


Error to check whether the operation has terminated successfully or with an error 


value. 


See Also | OleQueryReleaseMethod, OleQueryReleaseStatus 


OleQueryReleaseMethod 


#include <ole.h> 


OLE_RELEASE_METHOD OleQueryReleaseMethod(/pobj) 


LPOLEOBJECT Ipobj; /* address of object to query 


=) 


The OleQueryReleaseMethod function finds out the operation that finished for 


the specified object. 


Parameters lpobj 


Points to an object for which the operation is to be auenee 


Return Value The return value indicates the server operation (method) that finished. It can be 


one of the following values: 


Value 


OLE_ACTIVATE 
OLE_CLOSE 


OLE_COPYFROMLNK 


OLE_CREATE 


OLE_CREATEFROMFILE 
OLE_CREATEFROMTEMPLATE 
OLE_CREATEIN VISIBLE 
OLE_CREATELINKFROMFILE 


OLE_DELETE 
OLE_EMBPASTE 


mY TATYWYDMA aT 
COLL _LNBPASTL 


OLE =LOADFROMS TREAM 


OLE_NONE 
_OLE_OTHER 
OLE_RECONNECT 


Server operation 


Activate 

Close | 
CopyFromLink (autoreconnect) 
Create 

CreateFromFile 
CreateFromTemplate 
CreateInvisible 
CreateLinkFromFile 


Object Delete 


Paste and Update 

Da ntanl indy Carwtrnwnnnnnant’ 

id QOUW LUITIN (au. WeVLILIEUL) 

LoadFromStream culoreconnecl) 

No operation active 

Other miscellaneous asynchronous Sperations 
Reconnect | 


Comments 


See Also 
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Value Server operation 


OLE_REQUESTDATA OleRequestData 
OLE_RUN Run 
OLE_SERVERUNLAUNCH Server is stopping 
OLE_SETDATA OleSetData 
OLE_SETUPDATEOPTIONS Setting update options 
OLE_SHOW | Show 

OLE_UPDATE Update 


If the pointer passed in the lpobj parameter is invalid, the function returns 
OLE_ERROR_OBJECT. 


A client application receives the OLE_RELEASE notification when an asynchro- 
nous operation has ended. The client can then call OleQueryReleaseMethod to 
check which operation caused the library to send the OLE_RELEASE notification. 
The client calls OleQueryReleaseError to determine whether the operation termi- 
nated successfully or with an error value. | 


OleQueryReleaseError, OleQueryReleaseStatus 


OleQueryReleaseStatus - Pie es [3.1 | 


#include <ole.h> 


OLESTATUS OleQueryReleaseStatus(/pob)) 
LPOLEOBJECT Ipobj; /* address of object to query */ 


Parameters 


Return Value 


See Also 


The OleQueryReleaseStatus function determines whether an operation has 


finished for the specified object. 


lpobj 
Points to an object for which the operation is queried. 


The return value, if the function is successful, is either OLE_BUSY if an operation 
is in progress or OLE_OK. If the pointer passed in the /pobj parameter is invalid, 
the function returns OLE_ ERROR OBJECT. 


OleQueryReleaseError, OleQueryReleaseMethod | 
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OleQueryServerVersion rat] 


#include <ole.h> 


DWORD OleQueryServerVersion(void) 


Parameters 


Return Value 


See Also 


OleQuerySize 


#include <ole.h> 


The OleQueryServerVersion function retrieves the version number of the server 


library. 

This function has no parameters. 

The return value is a doubleword value. The major version number is in the 
low-order byte of the low-order word, and the minor version number is in the high- 


order byte of the low-order word. The high-order word is reserved. 


OleQueryClientVersion 


OLESTATUS OleQuerySize(/pObject, pdwSize) 7 
LPOLEOBJECT [pObject; —_‘/* address of object to query **/ 
DWORD FAR? pdwSize; /* address of size of object | 


Parameters 


Return Value 


See Also 


The OleQuerySize function retrieves the size of the specified object. 


[pObject 
Points to the object to query. 

pdwSize 
Points to a variable for the size of the object. This variable contains the size of 
the object when the function returns. 


The return value is OLE_OK if the function is successful. Otherwise, itisanerror 
value, which may be one of the following: : 


OLE_ERROR_BLANK 
OLE_ERROR_MEMORY 
OLE_ERROR_OBJECT 


OleLoadFromStream 
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OleQueryType | [3.1] 
#include <ole.h> 


OLESTATUS OleQueryType(/pObject, IpType) 
LPOLEOBJECT [pObject; /* address of object to query */ 
LONG FAR® [pType; /* address of type of object si | 


The OleQueryType function checks whether a specified object is embedded, 
linked, or static. 


Parameters — lpObject 
Points to the object for which the type is to be queried. 
ipType | | 
Points to a long variable that contains the type of the object when the function 
returns. This parameter can be one of the following values: 


Value Meaning 
OT_EMBEDDED __ Object is embedded. 
OT_LINK Object is a link. 
OT_STATIC Object is a static picture. 
Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 


OLE_ERROR_GENERIC 
OLE_ERROR_OBJECT 


See Also OleEnumFormats 


OleReconnect : 4] 
#include <ole.h> 


OLESTATUS OleReconnect(ipObject) 
LPOLEOBJECT (pObject; _—_—/* address of object to reconnect to i e 


The OleReconnect function reestablishes a link to an open linked object. If the 
specified object is not open, this function does not openit. 
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Parameters 


Return Value 


Comments 


See Also 


OleRegisterClientDoc 


#include <ole.h> 


[pObject 
Points to the object to reconnect to. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_NOT_LINK 
OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


A client application can use OleReconnect to keep the presentation for a linked 
object up-to-date. 


OleActivate, OleClose, OleUpdate 


OLESTATUS OleRegisterClientDoc(/pszClass, lpszDoc, reserved, IplhDoc) 


LPCSTR [pszClass; /* address of string for class name */ 
LPCSTR I[pszDoc; /* address of string for document name 1 
LONG reserved; | /* reserved of 
LHCLIENTDOC FAR* IplhDoc; /* address of handle of document st 


Parameters 


The OleRegisterClientDoc function registers an open client document with the 
library and returns the handle of that document. 


IpszClass 
Points to a null-terminated string specifying the class of the client document. 


_ IpszDoc 


Points to a null-terminated string specifying the location of the client document. | 
(This value should be a ew qualified path.) 


reserved 
~ Reserved. Must be zero. 


[plhDoc 

_ Points to the handle of the client docuitient when the fanetion returns. This 
handle is used to identify the document in other document-management func- 
tions. 


Return Value 


Comments 


See Also 
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The return value is OLE_OK if the function is ieee Otherwise, it 1S an error 
value, which may be one of the following: 


OLE_ERROR_ALREADY_REGISTERED 
OLE_ERROR_MEMORY 
OLE_ERROR_NAME 


When a document being copied onto the clipboard exists only because the client 


application is copying Native data that contains objects, the name specified in the 
lpszDoc parameter must be Clipboard. 


Client applications should register open documents with the library and notify the 
library when a document is renamed, closed, saved, or restored to a changed state. 


OleRenameClientDoc, OleRevertClientDoc, OleRevokeClientDoc. 
OleSavedClientDoc 


OleRegisterServer 


- #include <ole. h> 


OLESTATUS OleRegisterServer(ipszClass, lpsrvr, lplhserver, hinst, srvruse) 


LPCSTR [pszClass; 7* address of string for class name */ 
LPOLESERVER Ipsrvr; /* address of OLESERVER structure st 
LHSERVER FAR? Iplhserver; /* address of serverhandle */ 
-HINSTANCE hinst; /* instance handle ‘| 
OLE_ SERVER_ USE STVrUSe} /* single or multiple instances */ 


Parameters © 


The OleRegisterServer function registers the specified server, class name, angi in- 
stance with the server library. : 


IpszClass 
Points toa null-terminated string specifying the class name being registered. 


lpsrvr a 
Points to an OLESERVER structure allocated and initialized aby the server TaD 
plication. | 


lplhserver 
Points to a variable of type LHSERVER i in which the library stores the handle : 
_ of the server. This handle is used in such functions as OleRegisterServerDoc 3 


se and OleRevokeServer. 
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Return Value 


Comments 


See Also 


OleRegisterServerDoc 


#include <ole.h> 


hinst oe 
Identifies the instance of the server application. This handle is used to ensure 
that clients connect to the correct instance of a server application. 


STVrUuse 
_ Specifies whether the server uses a single instance or multiple instances to sup- 
port multiple objects. This value must be either OLE_SERVER_SINGLE or 
OLE_SERVER_MULTI. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_CLASS 
OLE_ERROR_MEMORY 
OLE_ERROR_PROTECT_ONLY 


When the server application starts, it creates an OLESERVER structure and calls 
the OleRegisterServer function. Servers that support several class names can allo- 
cate a structure for each or reuse the same structure. The class name is passed to 
server-application functions that are called through the library, so that servers 
supporting more than one class can check which class is being requested. 


The srvruse parameter is used when the libraries open an object. When 
OLE_SERVER_MULTI is specified for this parameter and all current instances 
are already editing an object, a new instance of the server is started. Servers that 
support the multiple document interface (MDI) typically specify 
OLE_SERVER_SINGLE. 


_ OleRegisterServerDoc, OleRevokeServer 


OLESTATUS OleRegisterServerDoc(/hsrvr, lpszDocName, lpdoc, Iplhdoc) 


LHSERVER l/hsrvr; /* server handle */ 
LPCSTR [pszDocName; /* address of string for document name | i 
LPOLESERVERDOC Ipdoc; _ /* address of OLESERVERDOC structure ed 
LHSERVERDOC FAR* [plhdoc; —_—‘/* handle of registered document ) sf 


_ The OleRegisterServerDoc function registers a document with the server library 


in case other client applications have links to it. A server application uses this func- 
tion when the server is started with the /Embedding filename option or when it 
creates or opens a document that is not requested by the library. 


OleRelease 709 


Parameters lhsrvr 

Identifies the server. Server applications obtain this adadie by calling the 
OleRegisterServer function. 

lpszDocName 
Points to a null-terminated string specifying the permanent name for the docu- 
ment. This parameter should be a fully qualified path. 

lpdoc 
Points to an OLESERVERDOC structure allocated and iaitialived by the serv- 
er application. - 

lplhdoc 
Points to a handle that will identify the document. This parameter points to the 
handle when the function returns. 


Return Value | If the function is successful, the return value is OLE_OK. Otherwise, it is an error 
| value, which may be one of the ronowane: 


~ OLE_ERROR_ ADDRESS 
OLE ERROR HANDLE 
OLE_ERROR_MEMORY 


Comments If the document was created or opened in response to a request from the server 
library, the server should not register the document by using OleRegisterServer- 
Doc. Instead, the server should return a pointer to the OLESERVERDOC struc- 
ture through the parameter to the relevant function. 


See Also | OleResisterServer. OleRevokeServerDoc 


OleRelease ese eee 
#include <ole.h> | | 


OLESTATUS OleRelease(/pObject) | 
LPOLEOBJECT lpObject; —_/* address of object to release al j 


The OleRelease function releases an object from memory and closes it if it was" 
open. This function does not indicate that the object has been deleted from the 
client document. . 


Parameters | pObject 
| . Points to the object to release. 
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Return Value If the function is successful, the return value 1 is OLE_OK. Otherwise, it is an error 
value, which may be one of the Henne: 


OLE_BUSY 
OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


Comments The OleRelease function should be called for all obec when closing the client 
| document. 
See Also OleDelete 


OleRename _ Eu 


#include <ole.h> 


OLESTATUS OleRename(/pObject, lpszNewname) 
LPOLEOBJECT [pObject; _‘/* address of object being renamed */ 
LPCSTR IpszNewname; /* address of string for new object name sf | 


The OleRename function renames an object. 


Parameters [pObject 
Points to the object that is being renamed. 


[pszNewname 
Points to a null-terminated string specifying the new name of the object. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
7 value, which may be OLE_ERROR_OBJECT. 


Comments Object names need not be seen by the user. They must be unique within the con- 
taining document and must be preserved when the document is saved. 


See Also OleQueryName 
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OleRenameClientDoc - aa] 
#include <ole.h> | 7 | 


OLESTATUS OleRenameClientDoc(/hClientDoc, IpszNewDocname) | 
LHCLIENTDOC [hClientDoc; /* handle of client document | */ 
LPCSTR [pszNewDocname; /* address of string for new document name */ 


The OleRenameClientDoc function informs the client library that a document has 
been renamed. A client application calls this function when a document name has 
changed—for example, when the user chooses the Save or Save As command 
from the File menu. . 


- Parameters IhClientDoc | 
Identifies the document that has been renamed. 


lpszNewDocname 
Points to a null-terminated sting specifying the new name of the document. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
| value, which may be OLE_ERROR_ HANDLE. | 


Comments | Client applications should register open documents with the library and notify the 
| library when a document is renamed, plosed, saved, or restored to a changed state. 
~ See Also OleRegisterClientDoc, C OleRevertClientDoc, OleRevokeClientDoc, 
OleSavedClientDoc os 


OleRenameServerDoc ie 7 Fa 


#include <ole.h>_ 


OLESTATUS OleRenameServerDoc(/hDoc, IpscDocNeme) | ere 
LHSERVERDOC [hDoc; /* handle of document , 3 a 
LPCSTR pega niiea /* address of string for path and filename ee at) an 


The OleRenameServerDoc function informs the : server brary that a document 
has been renamed. , | 3 


Parameters et -IhDoc 
| Identifies the document that has been renamed. 
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lpszDocName 
Points to a null-terminated string specifying the new name of the document. 
This parameter is typically a fully qualified path. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_HANDLE 
OLE_ERROR_MEMORY 


Comments The OleRenameServerDoc function has the same effect as sending the 
OLE_RENAMED notification to the client application’s callback function. The 
server application calls this function when it renames a document to which the ac- 
tive links need to be reconnected or when the user chooses the Save As command 
from the File menu while working with an embedded object. 


Server applications should register open documents with the server library and 
notify the library when a document is renamed, closed, saved, or restored to a 
changed state. 


See Also OleRegisterServerDoc, OleRevertServerDoc, OleRevokeServerDoc, 
z OleSavedServerDoc 


OleRequestData - [31] 


#include <ole.h> 


OLESTATUS OleRequestData([pObject, cfFormat) 
LPOLEOBJECT [pObject /* address of object to query a 
OLECLIPFORMAT cfFormat;. _/* format for retrieved data ey 


The OleRequestData function requests the library to retrieve data in a specified 
format from a server. 


Parameters lpObject 
7 Points to the object that is associated with the server from which data is to be re- 
trieved. : 


cfFormat 
Specifies the format in which data is to be returned. This parameter can be one 
of the predefined clipboard formats or the value returned by the peer: 
ClipboardFormat function. 


Return Value 


Comments 


| See Also 
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The return value is OLE_OK if the function is successful. Otherwise, it 1s an error 


value, which may be one of the following: 


OLE_BUSY © | 
OLE_ERROR_NOT_OPEN 
OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


The client application should be connected to the server application when 
the client calls the OleRequestData function. When the client receives the 
OLE_RELEASE notification, it can retrieve the data from the object by using the 


~ OleGetData function or query the data by using such functions as OleQuery- 


Bounds. 


If the requested data format is the same as the presentation data for the ROIs the 
library manages the data and updates the presentation. | 


The OleRequestData function returns OLE_WAIT_FOR_RELEASE if the server 
1S busy. In this case, the application should continue to dispatch messages until it 
receives a callback notification with the OLE_RELEASE argument. 


OleEnumFormats, OleGetData. OleSetData, RegisterClipboardFormat 


OleRevertClientDoc SR (az 


#include <ole.h> 


OLESTATUS OleRevertClientDoc(JhClientDoc) | 
LHCLIENTDOC lhClientDoc; /* handle of client document sal 


Parameters 


Return Value 


Comments - 


The OleRevertClientDoc function informs the library that a document has been 
restored to a previously saved condition. | 


lhClientDoc | ae 
Identifies the document that has been restored to its saved State. | 


The return value is OLE_ OK if the function is successful. Otherwise, it is an error 
value, which may be OLE_ERROR_HANDLE. | | 


—Aclient application should call the OleRevertClientDoc function when it treloads 
a document without saving cg to the document. 
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Client applications should register open documents with the library and notify the 
library when a document is renamed, closed, saved, or restored to a saved state. 


See Also OleRegisterClientDoc, OleRenameClientDoc, OleRevokeClientDoc, 
OleSavedClientDoc 


OleRevertServerDoc oo | | 3.1 | 


#include <ole.h> 


OLESTATUS OleRevertServerDoc(/iDoc) 
LHSERVERDOC [hDoc; /* handle of document */ 


The OleRevertServerDoc function informs the server library that the server has 
restored a document to its saved state without closing it. 


Parameters lhDoc 
3 Identifies the document that has been restored to its saved state. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be OLE_LERROR_HANDLE. | 


Comments Server applications should register open documents with the server library and 
notify the library when a document is renamed, closed, saved, or restored to a 
saved state. | 


See Also | OleRegisterServerDoc, OleRenameServerDoc, OleRevokeServerDoc, 
OleSavedServerDoc 


OleRevokeClientDoc [3.1] 


#include <ole.h> 


OLESTATUS OleRevokeClientDoc(/iClientDoc) 
LHCLIENTDOC [hClientDoc; /* handle of client document sf 


The OleRevokeClientDoc function informs the client library that a document is 
no longer open. 


Parameters 


Return Value 


Comments 


See Also 
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[hClientDoc | 
Identifies the document that is no longer open. This handle is invalid following 
the call to OleRevokeClientDoc. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_HANDLE 
OLE_ERROR_NOT_EMPTY 


The client application should delete all the objects in a document before cans 
OleRevokeClientDoc. 


Client applications should register open documents with the library and notify the 
library when a document is renamed, closed, saved, or restored to a changed state. 


OleRegisterClientDoc, OleRenameClientDoc, OleRevertClientDoc, 
OleSavedClientDoc 


OleRevokeObject “a 4 +2 


#include <ole.h> 


OLESTATUS OleRevokeObject(/pClient) 
LPOLECLIENT [pClient; /* address of OLECLIENT structure */ 


Parameters _— 


Return Value 


See Also 


The OleRevokeObject function revokes access to an object. A server application 
typically calls this function when the user destroys an object. 


[pClient 
Points to the OLECLIENT structure associated with the object peing revoked. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value. 


OleRevokeServer, OleRevokeServerDoc 
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OleRevokeServer 


#include <ole.h> 


OLESTATUS OleRevokeServer(JhServer) 
LHSERVER [hServer; /* server handle si 


Parameters 


Return Value 


Comments 


See Also 


OleRevokeServerDoc 


#include <ole.h> 


The OleRevokeServer function is called by a server application to close any regis- 
tered documents. 


lhServer 


Identifies the server to revoke. A server application obtains this handle in a call 
to the OleRegisterServer function. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_HANDLE 
OLE_WAIT_FOR_RELEASE 


The OleRevokeServer function returns OLE_-WAIT_FOR_RELEASE if com- 
munications between clients and the server are in the process of terminating. In 
this case, the server application should continue to send and dispatch messages 
until the library calls the server’s Release function. 


OleRegisterServer, OleRevokeObject, OleRevokeServerDoc 


OLESTATUS OleRevokeServerDoc(/hdoc) 7 
LHSERVERDOC lhdoc; —_—/* document handle | 


Parameters 


The OleRevokeServerDoc function revokes the specified document. A server ap- 
plication calls this function when a registered document is being closed or other- 
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lhdoc 
Identifies the document to revoke. This handle was returned by a call to the 
OleRegisterServerDoc function or was associated with a document by using 
one of the server-supplied functions that create documents. 
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Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_HANDLE 
OLE_WAIT_FOR_RELEASE 


Comments If this function returns OLE_WAIT_FOR_RELEASE, the server application 
should not free the OLESERVERDOC structure or exit until the library calls the 
server’s Release function. | 


See Also _ OleRegisterServerDoc, OleRevokeObject, OleRevokeServer 


OleSavedClientDoc — [3.1] 


#include <ole.h> 


OLESTATUS OleSavedClientDoc(JhClientDoc) 
LHCLIENTDOC ihClientDoc; /* handle of client document */ 


The OleSavedClientDoc function informs the client libjary that a document has 
been saved. 


Parameters IhClientDoc 
Identifies the document that has been saved. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
| value, which may be OLE_LERROR_HANDLE. 


Comments Client applications should register open documents with the client library and 
notify the library when a document is renamed, closed, saved, or restored to a 
saved state. 


See Also. OleRegisterClientDoc, O@leReaaineClientDoc OleRevertClientDoc, 
OleRevokeClientDoc 
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OleSavedServerDoc 


#include <ole.h> 


OLESTATUS OleSavedServerDoc(/;Doc) 
LHSERVERDOC /[hDoc; /* handle of document st | 


Parameters 


Return Value 


~ Comments 


See Also | 


The OleSavedServerDoc function informs the server library that a document fas 


been saved. 


lhDoc 
Identifies the document that has been saved. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_CANT_UPDATE_CLIENT 
OLE_ERROR_HANDLE 


The OleSavedServerDoc function has the same effect as sending the 
OLE_SAVED notification to the client application’s callback function. The server | 
application calls this function when saving a document or when updating an 
embedded object without closing the document. 


When a server application receives OLE_LERROR_CANT_UPDATE_CLIENT as 
an error value, it should display a message box indicating that the user cannot up- 
date the document until the server terminates. 


Server applications should register open documents with the server library and 


notify the library when a document is renamed, closed, saved, or Restores toa 
saved state. 


OleRegisterServerDoc, OleRenameServerDoc. OleRevertServerDoc, 


-OleRevokeServerDoc 
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OleSaveToStream [3.1 | 


#include <ole.h> | 


OLESTATUS OleSaveToStream(/pObject, lpStream) | 
LPOLEOBJECT [pObject; /* address of object to save if 
LPOLESTREAM IpStream; /* address of OLESTREAM structure | 


The OleSaveToStream function saves an object to the stream. 


Parameters [pObject — 
Points to the object to be saved to the stream. 


[pStream 
Points to an OLESTREAM structure allocated and initialized by the client ap- 
plication. The library calls the Put function in the OLESTREAM structure to _ 


store the data from the object. 


Return Value The ‘earn value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_ERROR_BLANK 
OLE_ERROR_MEMORY 
OLE_ERROR_OBJECT 
OLE_ERROR_STREAM 


Comments An application can use the OleQuerySize function to find the number of bytes to 
allocate for the object. 


See Also OleLoadFromStream, OleQuerySize 


OleSetBounds - aa] 


#include <ole.h> 


OLESTATUS OleSetBounds(/pObject, IprcBound) 
LPOLEOBJECT [pObject; —_—/* address of object ai 
RECT FAR® [prcBound; /* address of structure for bounding rectangle */ 


The OleSetBounds function sets the coordinates of the bounding rectangle for the 
specified object on the target device. 
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Parameters 


Return Value 


Comments 


See Also 


OleSetColorScheme 


H 
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[pObject ess 
Points to the object for which the bounding rectangle is set. 


lprcBound ? 
Points to a RECT structure containing the coordinates of the bounding 
rectangle. The coordinates are specified in MM_HIMETRIC units. Neither the 
width nor height of an object should exceed 32,767 MM_HIMETRIC units. 


The return value is OLE_OK if the function is successful. Otherwise, it i an error — 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_MEMORY 
OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


The OleSetBounds function returns OLE_-.ERROR OBJECT when it is called for 
a linked object. 


The OleSetBounds function is ignored for linked objects, because the size of a 
linked object is determined by the source document for the link. 


A client application uses OleSetBounds to change the bounding rectangle. The 
client does not need to call OleSetBounds every time a server is opened. 


The bounding rectangle specified in the OleSetBounds function does not neces- 
sarily have the same dimensions as the rectangle specified in the call to the Ole- 
Draw function. These dimensions may be different because of the view scaling — 
used by the container application. An application can use OleSetBounds to cause 
the server to reformat the picture to fit the rectangle more closely. 


In the MM_HIMETRIC mapping mode, the positive y-direction is up. 


OleDraw, OleQueryBounds, SetMapMode 


OLESTATUS OleSetColorScheme(/pObject, ipPalette) | ; 
LPOLEOBJECT [pObject; /* address of object | si 
const LOGPALETTE FAR?® /[pPalette; /* address of preferred palette | 


Parameters 


Return Value 


Comments 
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The OleSetColorScheme function specifies the palette a client application recom- 
mends be used when the server application edits the specified object. The server 
application can ignore the recommended palette. 


[pObject 
Points to an OLEOBJECT structure describing the object for which a palette 
is recommended. 


[pPalette 
Points toa LOGPALETTE structure specifying the recommended palette. 


The return value is OLE_OK if the function is successful. Otherwise. it iS an error 
value, which may be one of the following: 


OLE_ BUSY | 
OLE_ERROR_COMM 


OLE_ERROR_MEMORY 


OLE_ERROR_OBJECT 
OLE_ERROR_PALETTE 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


The OleSetColorScheme function returns OLE_ERROR_OBJECT when it is 
called for a linked object. 


A client application uses OleSetColorScheme to change the color scheme. The 
client does not need to call OleSetColorScheme every time a server is opened. 


The first palette entry in the LOGPALETTE structure specifies the foreground 
color recommended by the client application. The second palette entry specifies 
the background color. The first half of the remaining palette entries are fill colors, 
and the second half are colors for lines and text. 


Client applications should specify an even number of palette entries. When there is 
an uneven number of entries, the server interprets the odd entry as a fill color; that 
is, if there are five entries, three are interpreted as fill colors and two as line and — 
text colors. 


When server applications render metafiles, they should use the suggested palette. _ 
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OleSetData 


#include <ole.h> 


OLESTATUS OleSetData(/pObject, cfFormat, hData) 
LPOLEOBJECT [pObject; —sS*/* address of object i) a 
OLECLIPFORMAT cfFormat; /* format of data to send sr 


HANDLE hData; 


Parameters 


Return Value 


See Also 


/* memory containing data | 


The OleSetData function sends data in the specified format to the server as- 
sociated with a specified object. 


lpObject | 
Points to an object specifying the server to which data is to be sent. 


cfFormat 
Specifies the format of the data. 


hData 
Identifies a memory object containing the data in the specified format. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_BLANK 
OLE_ERROR_MEMORY 
OLE_ERROR_NOT_OPEN 
OLE_ERROR_OBJECT 
OLE_WAIT_FOR_RELEASE 


If the specified object cannot accept the data, the function returns an error value. If 
the server is not open and the requested data format is different from the format of 
the presentation data, the return value is OLE_ERROR_NOT_OPEN 


-—OleGetData, OleRequestData - 
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OleSetHostNames e ee — (8A 


#include <ole.h> 


OLESTATUS OleSetHostNames(/pObject, lpszClient, lpszClientObj) , | 
LPOLEOBJECT [pObject; —_—/* address of object if 


LPCSTR I[pszClient; /* address of string with name of client app a | 
LPCSTR IpszClientObj; /* address of string with client’s name for object | 


The OleSetHostNames function specifies the name of the client application and 
the client’s name for the specified object. This information is used in window _ 
titles when the object is being edited in the server application. 


Parameters [pObject 
Points to the object for which a name is to be set. 


lpszClient 
Points to a null-terminated string specifying the name of the client application. 


lpszClientObj 
Points to a null-terminated string specifying the client’s name for the object. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error — 
value, which may be one of the following: 7 


OLE_BUSY 
OLE_ERROR_MEMORY | 
OLE_ERROR_OBJECT | 
OLE_WAIT_FOR_RELEASE 


The OleSetHostNames function returns OLE. ERROR _OBJ ECT ice it is called 
for a linked object. 


Comments — When a server application is started for editing of an embedded object, it displays 
| | in its title bar the string specified in the /pszClientObj parameter. The object name 
specified in this string should be the name of the client document containing the 
object. | | 


A client application uses OleSetHostNames to set the name of an object the first 
time that object is activated or to change the name of an object. The client does not 
_ need to call OleSetHostNames every time a server is opened. 
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OleSetLinkUpdateOptions 


#include <ole.h> 


OLESTATUS OleSetLinkUpdateOptions(/pObject, UpdateOpt) 
LPOLEOBJECT pObject; /* address of object i 
OLEOPT_UPDATE UpdateOpt; _‘/* link-update options a | 


Parameters 


Return Value 


See Also 


The OleSetLinkUpdateOptions function sets the link-update options for the pre- 
sentation of the specified object. 


| [pObject 


Points to the object for which the link-update option is set. 


UpdateOpt 
Specifies the link-update option for the specified object. This parameter can be 
one of the following values: 


Option Description 


oleupdate_always Update the linked object whenever possible. This option sup- 

ports the Automatic link-update radio button in the Links 
| dialog box. 

oleupdate_oncall Update the linked object only on request from the client ap- 
plication. This option supports the Manual link-update radio 
button in the Links dialog box. 

oleupdate_onsave Update the linked object when the source document is saved 
by the server. 


The return value is OLE_OK if the function is successful. Otherwise, it 1s an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_OBJECT 
OLE_ERROR_OPTION 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


~ OleGetLinkUpdateOptions 


SSR Re 
8 
geald 


OleSetTargetDevice 725 


OleSetTargetDevice — - EXNy 


#include <ole.h> 


OLESTATUS OleSetTargetDevice(/pObject, hotd) | 
LPOLEOBJECT /pObject; /* address of object i a 


HGLOBAL hotd; 


Parameters 


Return Value 


Comments 


/* handle of OLETARGETDEVICE structure tf 


The OleSetTargetDevice function specifies the target output device for an object. 


lpObject 
Points to the object for which a ee device is specitied. 


hotd 
Identifies an OLETARGETDEVICE structure that describes the target device 
for the Ont 


The return value is OLE | OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 

OLE_ERROR _MEMORY 
OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


_ The OleSetTargetDevice function allows a linked or embedded object to be for- 


matted correctly for a target device, even when the object is rendered on a differ- 
ent device. A client application should call this function whenever the target 
device changes, so that servers can be notified to change the rendering of the ob- 
ject, if necessary. The client application should call the OleUpdate function to en- 
sure that the information is sent to the server, so that the server can make the 


necessary changes to the object’s presentation. The client application should call 


the library to redraw the object if it receives a notification from the server that the 


Glee: has changed. 


A client application uses the OleSetTargetDevice function to change the target 
device. The client does not need to call OleSetTargetDevice every, time a server 1S 
opened. 7 7 | 


726 OleUnblockServer 


OleUnblockServer — | [ 3.1 | 


#include <ole.h> 


OLESTATUS OleUnblockServer(/hSrvr, [pfRequest) 
LHSERVER /hSrvr; /* handle of server me, 
BOOL FAR® /[pfRequest; /* address of flag for more requests ae 


The OleUnblockServer function processes a request from a queue created by 
calling the OleBlockServer function. 


Parameters lhSrvr 
Identifies the server for which requests were queued. 


lpfRequest 
Points to a flag indicating whether there are further requests in the queue. If 
there are further requests in the queue, this flag is TRUE when the function re- 
turns. Otherwise, it is FALSE when the function returns. 


Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE ERROR HANDLE 
OLE ERROR MEMORY 


Comments A server application can use the OleBlockServer and OleUnblockServer func- 
tions to control when the server library processes requests from client applications. 
It is best to use OleUnblockServer outside the GetMessage function in a message 
_ loop, unblocking all blocked messages before getting the next message. Unblock- 
ing message loops should not be run inside server-defined functions that are called 
by the library. | 


See Also OleBlockServer 


OleUnlockServer faa] 
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- OLESTATUS OleUnlockServer(/Server) 
LHSERVER /hServer; _—s/* handle of server to unlock sf 


The OleUnlockServer function unlocks a server that was locked by the OleLock- 
Server function. 


Parameters 


Return Value 


Comments — 


See Also 


OleUpdate 


#include <ole.h> 
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hServer | 
Identifies the server to release from memory. This handle was retrieved by a 
call to the OleLockServer function. 


The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: | 


OLE ERROR HANDLE 
OLE_WAIT FOR RELEASE 


When the OleLockServer function is called more than once for a given server, the 
server’s lock count is incremented. Each call to OleUnlockServer decrements the 
lock count. The server remains locked until the lock count is zero. 


If the OleUnlockServer function returns OLE_WAIT_FOR_RELEASE, the appli- | 
cation should call the OleQueryReleaseStatus function to determine whether the — 
unlocking process has finished. In the call to OleQueryReleaseStatus, the applica- 
tion can cast the server handle to a long pointer to an object linking and embed- 
ding (OLE) object (LPOLEOBJECT): : 


= OleueryReleaseStatus((LPOLEOBJECT) 1 Thserver) ; 


When Cle Qucry RelenseStatin no evs returns OLE_ BUSY, the server has: | 


been unlocked. 


: OleLockServer. OleQueryReleaseStatus 3 


OLESTATUS OleUpdate(/pObject) 
LPOLEOBJECT /pObject; /* address of object **/ 


| Parameters 


The OleUpdate function updates the specified object. This function updates the — | 
presentation of the object and ensures that the object is up-to-date with ei ae to” 
any linked objects it contains. 


lpObject 
Points to the object to be indtest 
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Return Value The return value is OLE_OK if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


OLE_BUSY 
OLE_ERROR_OBJECT 
OLE_ERROR_STATIC 
OLE_WAIT_FOR_RELEASE 


See Also OleQueryOutOfDate 


OpenClipboard [2x | 


BOOL OpenClipboard(hwnd) 
HWND hwnd; /* handle of window to associate ownership with */ 


The OpenClipboard function opens the clipboard. Other applications will not be 
able to modify the clipboard until the CloseClipboard function is called. 


- Parameters hwnd 
Identifies the window to be associated with the open clipboard. 


Return Value _ The return value is nonzero if the function is successful. It is zero if another appli- 
cation or window has the clipboard opened. 


Comments — The window identified by the hwnd parameter will not become the owner of the 
clipboard until the EmptyClipboard function is called. 


See Also CloseClipboard, EmptyClipboard 


OpenComm | 


int OpenComm(/pszDevControl, cbInQueue, cbOutQueue) 


TDOOPD lana Nalantenle I% aAAraaa Af Aaiira rantral information */ 
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UINT cbhinQueue; /* size of receiving queue a | 
UINT cbOutQueue; /* size of transmission queue we 


The OpenComm function opens a communications device. 


Parameters 


Return Value 


Errors 


Comments 


Example 
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lpszDevControl 
Points to a null-terminated string that specifies the device in the form COMn or 
LPTn, where n is the device number. 


cbInQueue 
Specifies the size, in bytes, of the receiving queue. This parameter is ignored 
- for LPT devices. 


cbOutQueue 
Specifies the size, in bytes, of the transmission queue. This parameter is ig- 
nored for LPT devices. 


The return value identifies the open device if the function is successful. Otherwise, 
it is less than zero. 


If the function fails, it may return one of the following error values: 


Value Meaning | 

IE_BADID The device identifier is invalid or unsupported. 
TE_BAUDRATE The device’s baud rate is unsupported. 

IE_BYTESIZE The specified byte size is invalid. 

TE_DEFAULT The default parameters are in error. 

IE_HARDWARE The hardware is not available (is locked by another deviee).” 
IE_MEMORY The function cannot allocate the queues. 

IE_NOPEN ? The device is not open. 

IE_OPEN The device is already open. 


If this function is called with both queue sizes set to zero, the return value is 
TE_OPEN if the device is already open or IE_LMEMORY if the device is not open. 


Windows allows COM ports 1 through 9 and LPT ports | through 3. If the device | 


driver does not support a communications port number, the peo function 
will fail. 


The poninminic albus device is initialized to a default configuration. The Set- 
CommState function should be used to initialize the device to alternate values. 


The receiving and transmission queues are used by interrupt-driven device 
drivers. LPT ports are not interrupt driven—for these ports, the cbInQueue and 
cbOutQueue parameters are ignored and the queue size is set to zero. | | 


The following example uses the OpenComm function to open communications: 
port 1: | 
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idComDev = OpenComm("COM1", 1024, 128); 
if (idComDev < @) { 
ShowError(idComDev, "OpenComm") ; 
return Q; 


} 


err = BuildCommDCB("COM1:9600,n,8,1", &dcb); 
if (err < Q) { 

ShowError(cerr, "BuildCommDCB") ; 

return Q; 


} 


err = SetCommState(&dcb) ; 

if (err < Q) f{ 
ShowError(err, "SetCommState"); 
return @; 


See Also 3 CloseComm, SetCommState 


OpenDriver 34) 


HDRVR OpenDriver(/pDriverName, I[pSectionName, lParam) 


LPCSTR [pDriverName; /* address of driver name **/ 
LPCSTR IpSectionName; /* address of .INI file section name */ 
LPARAM /Param; /* address of driver-specific information | 


The OpenDriver function performs necessary initialization operations such as set- 
ting members in installable-driver structures to their default values. 


Parameters | IpDriverName 
Points to a null-terminated string that specifies the name of an installable driver. 


lpSectionName 
Points to a null-terminated string that specifies the name of a section in the 
SYSTEM.INI file. 


lParam | 
Specifies driver-specific information. 


Return Value The return value is a handle of the installable driver, if the function is successful. 
| Otherwise itis NULL. 
Comments The string to which [pDriverName points must be identical to the name of the in- | 


stallable driver as it appears in the SYSTEM_INI file. 
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If the name of the installable driver appears in the [driver] section of the 
SYSTEM.INI file, the string pointed to by /pSectionName should be NULL. Other- 
wise this string should specify the name of the section in SYSTEM.INI that con- 
tains the driver name. 


When an application opens a driver for the first time, Windows calls the Driver- 
Proc function with the DRV_LOAD, DRV_ENABLE, and DRV_OPEN mes- 
sages. When subsequent instances of the driver are opened, only DRV_OPEN is 
sent. 


The value specified in the /Param parameter is passed to the /Param2 parameter 
of the DriverProc function. 


See Also CloseDriver, DriverProc 


OpenFile coy [ 2.x ] 


HFILE OpenFile(/pszFileName, IpOpenBuff, fuMode) 


LPCSTR I[pszFileName; /* address of filename 3 
OFSTRUCT FAR* [pOpenBuff; /* address of buffer for file information **/ 
UINT fuMode; /* action and attributes | 


The OpenFile function creates, opens, reopens, or deletes a file. 


Parameters lpszFileName 
Points to a null-terminated string that names the file to be opened. The string 
must consist of characters from the Windows character set and cannot contain — 
wildcards. 


lpOpenBuff 
Points to the OFSTRUCT structure that will receive information about the file 
when the file is first opened. The structure can be used 1n subsequent calls to 
the OpenFile function to refer to the a file. The OFSTRUCT structure has 
_ the following form: 


typedef struct tagOFSTRUCT { /* of */ 
BYTE cBytes; 
BYTE fFixedDisk; 
UINT neErrCode; 
BYTE reserved[4]; 
BYTE szPathName[128]; 
} OFSTRUCT; 


The szPathName member of OFSTRUCT contains characters from the OEM | 
character set. 
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OpenFile | 


For a full description of this structure, see the M7 icrosoft Windows Program- 


mer’s Reference, Volume 3. 


fuMode 


Specifies the action to take and the attributes for the file. This parameter can be 
a combination of the following values: 


Value 


OF_CANCEL 


OF CREATE 
OF DELETE 
OF EXIST 
OF PARSE 


OF_PROMPT 


OF_READ 
OF_READWRITE 
OF_REOPEN 


OF_SEARCH 


OF_SHARE_COMPAT 


OF_SHARE_ DENY_NONE 


OF SHARE DENY READ 


OF_SHARE_DENY_WRITE 


Meaning 


Adds a Cancel button to the OF_PROMPT dialog 
box. Pressing the Cancel button directs OpenFile 
to return a file-not-found error message. | 


Creates a new file. If the file already exists, it is 
truncated to zero length. 


Deletes the file. 


Opens the file, and then closes it. This value is 
used to test for file existence. Using this value 
does not change the file date. 


Fills the OFSTRUCT structure but carries out no 
other action. 


Displays a dialog box if the requested file does 
not exist. The dialog box informs the user that 
Windows cannot find the file and prompts the 
user to insert the file in drive A. 


Opens the file for reading only. 
Opens the file for reading and writing. 


Opens the file using information in the reopen 
buffer. 


Windows searches in directories even when the 
file name includes a full path. 


Opens the file with compatibility mode, allowing 
any program on a given machine to open the file 
any number of times. OpenFile fails if the file 
has been opened with any of the other sharing 
modes. 


Opens the file without denying other programs 
read or write access to the file. OpenFile fails if 
the file has been opened in stand mode by 
any other program. 


Opens the file and denies other programs read 
access to the file. OpenFile fails if the file has 
been opened in compatibility mode or tor read 
access by any other program. 


Opens the file and denies other programs write 
access to the file. OpenFile fails if the file has 
been opened in compatibility or for write access 
by any other program. 


Return Value | 


Comments 


See Also 
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Value | Meaning 


OF_SHARE_EXCLUSIVE Opens the file with exclusive mode, denying 
other programs both read and write access to the 
file. OpenFile fails if the file has been opened in 
any other mode for read or write access, even by 
the current program. 

OF_VERIFY Compares the time and date in the OF_STRUCT 
with the time and date of the specified file. The 
function returns HFILE_ERROR if the dates and 
times do not agree. 


~ OF_WRITE Opens the file for writing only. 


The return value is an MS-DOS file handle if the function is successful. (This 
handle is not necessarily valid; for example, if the fuMode parameter is 
OF_EXIST, the handle does not identify an open file, and if the fuMode parameter 
is OF_DELETE, the handle is invalid.) The return value is HFILE_ERROR if an 
error occurs. 


If the IpszFileName parameter specifies a filename and extension only (or if the 
OF_SEARCH flag is specified), the OpenFile function searches for a matching 
file in the following directories (in this order): : 


1. 
2: 


ep 
6. 


The current directory. 


The Windows directory (the directory containing WIN.COM), whose path the 
GetWindowsDirectory function retrieves. | 


. The Windows system directory (the directory containing such system fies as 


GDI.EXE), whose path the GetSystemDirectory function retrieves. 


. The directory containing the executable file for the current task; the Get- | 


ModuleFileName function obtains the path of this directory. 
The directories listed in the PATH environment variable. 


The list of directories mapped in a network. 


To close the file after use, the application should call the _ Iclose function. 


GetSystemDirectory, GetWindowsDirectory 


734 Openicon 
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BOOL OpenIcon(hwnd) 
HWND hwnd; /* handle of window **/ 


The Opentcon function activates and displays a minimized window. Windows re- 
stores the window to its original size and position. 


Parameters - hwnd 
Identifies the window. 


Return Value — The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments Using OpenlIcon is the same as specifying the SW_SHOWNORMAL ag ina 
call to the Show Window function. 


See Also CloseWindow, IsIconic, ShowWindow 


OpenSound | | | [2x | 


int OpenSound(void) 


This function is obsolete. Use the Windows multimedia audio functions instead. 
For information about these functions, see the Microsoft Windows Multimedia Pro- 
grammer’s Reference. 


OutputDebugString 


void OutputDebugString(/pszOutputString) 
LPCSTR /pszOutputString; /* address of string to display */ 


The OutputDebugString function displays the specified character string on the 
debugging terminal if a debugger is running. 


Parameters 


Return Value © 


Comments 


Example 


See Also 


PaintRgn 
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lpszOutputString 
Points to a null-terminated string to be displayed. 


This function does not return a value. 


This function preserves all registers. 


The following example uses the OutputDebugString function to display informa- 
tion on the debugging terminal: 


OutputDebugString("\n\rcalling ValidateCodeSegments"™) ; 
ValidateCodeSegments(); 


OutputDebugString("\n\rdone") ; 


DebugOutput 


BOOL PaintRegn(hdc, hrgn) 


HDC hdc; 


HRGN hrgn; 


Parameters 


Return Value 


Example 


/* handle of device context | */ 
/* handle of region */ 


The PaintRgn function fills a region by using the current brush for the given 
device context. 


hdc | 
Identifies the device context that contains the region to be filled. 


hrgn | 
Identifies the region to be filled. The coordinates for the given region are 
specified in device units. 7 fot 


The return value is nonzero if the function is successful. Otherwise, it is zero. — 


The following example uses the current brush for a device context to fill an ellipti- 
cal region: | 


— 136 PatBlt 


See Also 


PaiBit 


HDC hdc; 
HRGN hrgn; 


hrgn = CreateEllipticRgn(10, 10, 110, 110); 
SelectObject(hdc, hrgn); : 
PaintRgn(hdc, hrgn); 


‘DeleteObject(hrgn); 


CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, 
CreatePatternBrush, CreateSolidBrush, FillRgn 


BOOL PatBlt(hdc, nLeftRect, nTopRect, nwidth, nheight, fdwRop) 


HDC hdc; 

int nLeftRect; 

int nTopRect; 

int nwidth; 

int nheight; 
DWORD fdwRop; 


Parameters 


/* handle of device context a 
/* x-coordinate top-left corner destination rectangle a 
/* y-coordinate top-left corner destination rectangle */ 
/* width of destination rectangle i 
/* height of destination rectangle | sy | 
/* raster operation | 


The PatBlt function creates a bit pattern on the specified device. The pattern is a 
combination of the selected brush and the pattern already on the device. The 
specified raster-operation code defines how the patterns are combined. 


hdc 
Identifies the device context. 


nLeftRect 
Specifies the logical x-coordinate of the upper-left corner of the rectangle that 
receives the pattern. 


nlopRect 
Specifies the logical y-coordinate of the upper-left corner of the rectangle that 
receives the pattern. 


nwidth 
Specifies the width, in igcieel units, of the rectangle that will receive the pattern. 


nheight 
Specifies the height, in logical units, of the rectangle that will receive the 
pattern. 


Return Value 


Comments 


Example 
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fdwRop 
Specifies the raster-operation oe that determines how the graphics device in- 
terface (GDI) combines the colors in the output operation. This parameter can 
be one of the following values: 


Value Meaning 

PATCOPY Copies the pattern to the destination bitmap. 

PATINVERT - Combines the destination bitmap with the pattern by using the 
, Boolean XOR operator. 

PATPAINT Paints the destination bitmap. 


DSTINVERT Inverts the destination bitmap. 
BLACKNESS Turns all output black. 
WHITENESS Turns all output white. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The raster operations listed for this function are a limited subset of the full 256 ter- 
nary raster-operation codes; in particular, a raster-operation code that refers to a 
source cannot be used. 


Not all devices support the PatBlIt function. To determine whether a device sup- 
ports PatBIt, an application can call the nee ee function with the 
RASTERCAPS index. 


The following example uses the CreateBitmap function to create a bitmap with a 
zig-zag pattern, and then uses the PatBlt function to fill the client area with that 
pattern: 


HDC hdc; 

HBITMAP hbmp; 

HBRUSH hbr, hbrPrevious; 
RECT rc; | 


int aZigzag[] = { @xFF, OxF7, @xEB, @xDD, @xBE, Ox7F, Q@xFF, QxFF }; 


hbmp = CreateBitmap(8, 8, 1, 1, aZigzag); 
hbr = CreatePatternBrush(hbmp) ; 


hdc = GetDC(hwnd) ; 


' UnrealizeObject(hbr); 
~hbrPrevious = SelectObject(hdc, hbr); 


GetClientRect(hwnd, &rc); 
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See Also 


PatBlt(hdc, rc.left, rc.top, 

rce.right - rc.left, rc.bottom - rc.top, PATCOPY); 
SelectObject(hdc, hbrPrevious); 
ReleaseDC( hwnd, hdc); 


DeleteObject(hbr); 
DeleteObject(hbmp) ; 


GetDeviceCaps 


PeekMessage Pax] 


BOOL PeekMessage(/pmsg, hwnd, uFilterFirst, uFilterLast, fuRemove) 


MSG FAR® Ipmsg; 
HWND hwna; 
UINT uFilterFirst; 
UINT uFilterLast; 
UINT fuRemove; 


Parameters 


/* address of structure for message * 
/* handle of filter window op 
/* first message a 
/* last message a 
/* removal flags | 


The PeekMessage function checks the application’s message queue for a message 
and places the message (if any) in the specified MSG structure. 


Ipmsg | 
Points to an MSG structure that will receive message information from the ap- 
plication’s message queue. The MSG structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND = hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; . 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


hwnd | 
identifies the window whose messages are to be examined. 


uFilterFirst 
Specifies the value of the first message in the range of messages to be examined. 


uFilterLast | | 7 
Specifies the value of the last message in the range of messages to be examined. 


Return Value 


Comments 
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fuRemove 
Specifies how messages are handled. This parameter can be a combination of - 
the following values (PM_NOYIELD can be combined with either 
PM_NOREMOVE or PM_REMOVE): 


Value Meaning 

PM_NOREMOVE Messages are not removed from the queue after processing 
by PeekMessage. | 

PM_NOYIELD Prevents the current task from halting at yielding system re- 
sources to another task. 

PM_REMOVE Messages are removed from the queue after processing by 
PeekMessage. 


The return value is nonzero if a message is available. Otherwise, it is zero. 


Unlike the GetMessage function, the PeekMessage function does not wait for a _ 
message to be placed in the queue before returning. It does, however, yield control 
to other tasks (if the PM_NOYIELD flag is not set). 


Peek Message retrieves only messages associated with the window identified by 
the hwnd parameter, or any of its children as specified by the IsChild function, 
and within the range of message values given by the uFilterFirst and uF ilterLast 
parameters. If hwnd is NULL, PeekMessage retrieves messages for any window 
that belongs to the application making the call. (PeekMessage does not retrieve 
messages for windows that belong to other applications.) If uFilterFirst and 

uF ilterLast are both zero, PeekMessage returns all available messages (no range 
filtering is performed). 


The WM_KEYFIRST and WM_KEYLAST flags can be used as filter values to re- 
trieve all key messages; the WM_MOUSEFIRST and WM_MOUSELAST flags 
can be used to retrieve all mouse messages. 


-PeekMessage does not remove WM_PAINT messages from the queue. The mes- 


Sages remain in the queue until processed. The GetMessage, PeekMessage, and 
WaitMessage functions yield control to other applications. These calls provide the — 
only way to let other applications run. If your application does not call any of 
these functions for long periods of time, other applications cannot run. 


As long as an application is in a PeekMessage loop, Windows cannot become _ 
idle. Therefore, an application should not remain in a PeekMessage loop after the 
application’s background processing has completed. 


When an application uses the PeekMessage function without removing the mes- 
sage and then calls the WaitMessage function, WaitMessage does not return until 
the message 1s received. Applications that use the PeekMessage function should 
remove any retrieved messages from the queue before calling WaitMessage. 
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Example The following example checks the message queue for keystrokes that have special 
meaning to the application. Note that the CheckSpecialKeys function is applica- 
tion-defined. 


MSG msg; 
BOOL fRetVal = TRUE; 


while (PeekMessage(&msg, NULL, @, @, PM_REMOVE)) { 


if (msg.message == WM QUIT) 
fRetVal = FALSE; 


if (CheckSpecialKeys(&msg)) /* application defined */ 
continue; 


TranslateMessage(&msg); 
DispatchMessage(&msg) ; 


} 
return fRetVal; 


See Also GetMessage, IsChild, PostAppMessage, SetMessageQueue, WaitMessage 


Pie : | [2x | 


BOOL Pie(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nxStartArc, nyStartArc, nxEndArc, 


nyEndArc) 

HDC hdc; /* handle of device context +) 
int nLeftRect; /* x-coordinate upper-left corner bounding rectangle si | 
int nTopRect; /* y-coordinate upper-left corner bounding rectangle — */ 
int nRightRect; /* x-coordinate lower-right corner bounding rectangle */ 
int nBottomRect; /* y-coordinate lower-right corner bounding rectangle ay | 
int nxStartArc; /* x-coordinate arc starting point 7 */ 
int nyStartArc; /* y-coordinate arc starting point */ 
int nxEndArc; /* x-coordinate arc ending point 7 */ 
int nyEndArc; /* y-coordinate arc ending point +} 

The Pie function draws a pie-shaped wedge by drawing an elliptical arc whose 

center and two endpoints are joined by lines. 
Parameters hdc 

Identifies the device context. 
nLeftRect 


Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle. 


Return Value 


Comments 
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nTopRect 
Specifies the logical y-coordinate of the upper-left corner of the bounding 
rectangle. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the bounding — 
rectangle. 


nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the bounding 
rectangle. 


nxStartArc | 
Specifies the logical x-coordinate of the arc’s starting pont This point does not 
have to lie exactly on the arc. | 


nyStartA rc 
Specifies the logical y-coordinate of the arc’s starting point. This point does not 
have to lie exactly on the arc. 


nxEndArc | 
Specifies the logical x-coordinate of the arc’s endpoint. This point does not 
have to lie exactly on the arc. 


—nyEndArc 


_ Specifies the logical y-coordinate of the arc’s endpoint. This point does not ~ 
have to lie exactly on the arc. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The center of the arc drawn by the Pie function is the center of the bounding 
rectangle specified by the nLeftRect, nTopRect, nRightRect, and nBottomRect pa- 
rameters. The starting and ending points of the arc are specified by the nxStartArc, 
nyStartArc, nxEndArc, and nyEndArc parameters. The function draws the arc by 
using the selected pen, moving in a counterclockwise direction. It then draws two 


_ additional lines from each endpoint to the arc’s center. Finally, it fills the pie-— | 


shaped area by Usiiie the current brush. 


If nxStartArc equals nxEndArc and nyStartArc equals nyEndArc, the result is an 


- ellipse with a single line from the center of the ellipse to the point (uxStartAre, 


nystarta rc) or (nxEndArc, nyiindA rc). 


The figure drawn by this function extends up to but does not include the right and 
bottom coordinates. This means that the height of the figure is nBottomRect — 
nTopRect and the width of the figure is nRightRect — nLefiRect. 


Both the width and the height of a rectangle must be greater than 2 units anid less 


than 32,767 units. 
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Example The following example uses a RECT structure to store the points that define the 
bounding rectangle and uses POINT structures to store the coordinates that 
specify the beginning and end of the wedge: 


HDC hdc; 

RECT re = { 10, 10, 180, 140 }; 
POINT ptStart = { 12, 12 }; 
POINT ptEnd = { 128, 135 }; 


Pie(hdc, rc.left, rc.top, rc.right, rc.bottom, 
ptStart.x, ptStart.y, ptEnd.x, ptEnd.y); 


See Also Chord 


PlayMetaFile [ 2.x | 
BOOL PlayMetaFile(hdc, hmf) 

HDC hdc; /* handle of device context */ 

HMETAFILE hf; /* handle of metafile */ 


The PlayMetaFile function plays the contents of the specified metafile on the 
given device. The metafile can be played any number of times. 


Parameters hdc 


Identifies the device context of the output device. 
hmf | 
Identifies the metafile to be played. 
Return Value © The return value is nonzero if the function is successful. Otherwise, it is Zero. 
Example The following example uses the CreateMetaFile function to create a device- 


context handle of a memory metafile, draws a line in the device context, retrieves 
a metafile handle by calling the CloseMetaFile function, plays the metafile by 
using the PlayMetaFile function, and finally deletes the metafile by using the 
DeleteMetaFile function: | 

HUG ndcmeta; 

HMETAFILE hmf; 


See Also 


PlayMetaFileRecord 
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hdcMeta = CreateMetaFile(NULL); 
MoveTo(hdcMeta, 10, 10); 
LineTo(hdcMeta, 100, 100); 

hmf = CloseMetaFile(hdcMeta); 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf); 


PlayMetaFileRecord 


void PlayMetaFileRecord(hdc, Ipht, Ipmr, cHandles) 


HDC hdc; /* handle of device context “3 | 
HANDLETABLE FAR*™ I[phit; /* address of table of object handles | */ 
METARECORD FAR* Ipmr; /* address of metafile record i 
UINT cHandles; /* number of handles in table i | 

The PlayMetaFileRecord function plays a metafile record by executing the 

graphics device interface (GDI) function contained in the record. 

Parameters hdc | | 
Identifies the device context of the output device. 
[pht 


Return Value 


Comments 


Example 


Points to a table of handles associated with the objects (pens, brushes, and so 
on) in the metafile. | 


lpmr | 
Points to the metafile record to be played. 


cHandles 
Specifies the number of handles in the handle table. 


This function does not return a value. 


An application typically uses this function in conjunction with the EnumMetafile 
function to modify and then play a metafile. 


The following example creates a dashed green pen and passes it to the callback | 
function for the EnumMetaFile function. If the first element in the array of object 


_ handles contains a handle, that handle is replaced by the handle of the green pen 


before the PlayMetaFileRecord function is called. (For this example, it is as- 
sumed that the table of object handles contains only one handle and that it is a pen 
handle.) — , 
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MFENUMPROC IpEnumMetaProc; 
HPEN hpenGreen; 


]pEnumMetaProc = (MFENUMPROC) MakeProcInstance( 

(FARPROC) EnumMetaFileProc, hAppInstance); 
hpenGreen = CreatePen(PS_DASH, 1, RGB(@, 255, @)); 
EnumMetaFile(hdc, hmf, IpEnumMetaProc, (LPARAM) &hpenGreen); 
FreeProcInstance((FARPROC) IpEnumMetaProc) ; 
DeleteObject(hpenGreen) ; 


int FAR PASCAL EnumMetaFileProc(HDC hdc, HANDLETABLE FAR* lpHTable, 
METARECORD FAR* I1pMFR, int cObj, BYTE FAR* IpClientData) 


{ 
if (lpHTable->objectHandle[@] != @) 
lpHTable->objectHandle[@] = *(HPEN FAR *) IpClientData; 
PlayMetaFileRecord(hdc, lpHTable, ]pMFR, cObj); 
return 1; 
} . 
See Also EnumMetafile, PlayMetaFile 


Polygon | 2.x | 


BOOL Polygon(hdc, Ippt, cPoints) 


HDC hdc; /* handle of device context */ 
const POINT FAR* [ppt; /* address of array with points for vertices =) 
int cPoints; /* number of points in array sa | 


The Polygon function draws a polygon consisting of two or more points (vertices) 
connected by lines. The system closes the polygon automatically, if necessary, by 
drawing a line from the last vertex to the first. Polygons are surrounded by a frame 
drawn by using the current pen and filled by using the current brush. 


Parameters hdc 
Identifies the device context. 


Ippt 
- Points to an array of POINT structures that specify the vertices of the polygon. 
_Each structure in the array specifies a vertex. The POINT structure has the fol- 
lowing form: , 
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typedef struct tagPOINT { /* pt */ 
int -xs 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


cPoints 
Specifies the number of vertices in the array. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The current polygon-filling mode can be retrieved or set by using the GetPolyFill- 
Mode and SetPolyFillMode functions. 


Example The following example assigns values to an array of points and then calls the 
Polygon function: — 


HDC hdc; 


POINT aPoints[3]; 


aPoints[0].x = 5@; 
aPoints[0].y = 10; 
aPoints[1].x = 250; 
aPoints[1l].y = 50; 
aPoints[2].x = 125; 
aPoints[2].y = 130; 


Polygon(hdc, aPoints, sizeof(aPoints) / sizeof(POINT)); 


See Also GetPolyFillMode, Polyline, PolyPolygon, SetPolyFillMode 


Polyline a ee 


BOOL Polyline(hdc, Ippt, cPoints) 


HDC hdc; /*handle of device context = af 
const POINT FAR* Ippt; /* address of array with points to connect *}. 
int cPoints; _. /* number of points in array — Pe eT) 


The Polyline function draws a set of line segments, connecting the specified 
points. The lines are drawn from the first point through subsequent points, using 
the current pen. Unlike the LineTo function, the Polyline function neither uses nor 
updates the current position. 
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Parameters hdc 
Identifies the device context. 


lppt 


point. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


Points to an array of POINT structures. Each structure in the array specifies a 


For a full description of this structure, see the Microsoft Windows Program- 


mer’s Reference, Volume 3. 


cPoints 


Specifies the number of points in the array. This value must be at least 2. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Example The following example assigns values to an array of points and then calls the 
Polyline function: 
HDC hdc; 


POINT aPoints[3]; 


aPoints[@].x = 5@; 
aPoints[@].y = 10; 
aPoints[1].x = 250; 
aPoints[1l].y = 5@; 
aPoints[2].x = 125; 
aPoints[2].y = 130; 


~ Polyline(hdc, aPoints, sizeof(aPoints) / sizeof(POINT)); 


See Also -LineTo, Polygon 


PolyPolygon 


BOOL PolyPolygon(hdc, [ppt, lpnPolyCounts, cPolygons) 

HDC hdc; /* handle of device context 

const POINT FAR* [ppt; /* address of array with vertices 
int FAR* lpnPolyCounts; /* address of array with point counts 
int cPolygons; /* number of polygons to draw 


*/ 
| 
= 
*/ 
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The PolyPolygon function creates two or more polygons that are filled by using 
the current polygon-filling mode. The polygons may be disjoint or overlapping. 


_ Parameters hdc | 
Identifies the device context. 


[ppt 
Points to an array of POINT structures. Each structure in the array specifies a 
vertext of a polygon. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; | 
int y; 

} POINT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. 


[pnPolyCounts 
Points to an array of integers, each of which specifies the number of points in 
one of the polygons in the array pointed to by the /ppt parameter. 


cPolygons 
Specifies the number of polygons to be drawn. This value must be at least 2. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments _ Each polygon specified in a call to the PolyPolygon function must be closed. Un- | 


like polygons created by the Polygon function, the polygons created by Poly- 
Polygon are not closed automatically. 


The PolyPolygon function creates two or more polygons. To create a single poly- 
gon, an application should use the Polygon function. 


The current polygon-filling mode can be retrieved or set by using the eg owers 
Mode and SetPolyFillMode functions. 


Example The following example draws two overlapping polygons by assigning values to an 
array of points and then calling the PolyPolygon function: 3 
“HDC hdc; 


POINT aPolyPoints[8]; 
int aVertices[] = { 4, 4 }; 


aPolyPoints[@].x = 50; 
aPolyPoints[@].y = 10; 
aPolyPoints[1].x = 250; 
aPolyPoints[1].y = 5@; 
3 x = 125; 


aPolyPoints[2]. 
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aPolyPoints[2].y = 130; 
aPolyPoints[3].x = 50; 
aPolyPoints[3].y = 10; 
aPolyPoints[4].x = 100; 
aPolyPoints[4].y = 25; 
aPolyPoints[5].x = 300; 
aPolyPoints[5].y = 125; 
‘aPolyPoints[6].x = 7@; 
aPolyPoints[6].y = 15@; 
aPolyPoints[7].x = 100; 
aPolyPoints[7].y = 25; 


PolyPolygon(hdc, aPolyPoints, aVertices, 
sizeof(aVertices) / sizeof(int)); 


See Also GetPolyFillMode, Polygon, Polyline, SetPolyFillMode 


PostAppMessage [2x | 


BOOL PostAppMessage(htask, uMsg, wParam, lParam) 


HTASK htask; /* handle of task to receive message */ 
UINT uMsg; /* message to post =] 
~WPARAM wParam; /* first message parameter */ 
LPARAM /Param; /* second message parameter | 


The PostAppMessage function posts (places) a message in the message queue of 
the given application (task) and then returns without waiting for the application to 
process the message. The application to which the message is posted retrieves the 
message by calling the GetMessage or PeekMessage function. The hwnd mem- 
ber of the returned MSG structure is NULL. 


Parameters htask 
| Identifies the task to which the message is posted. The GetCurrentTask func- 
tion returns this handle. 


uMsg 
Specifies the type of message to be posted. 


wParam 
Specifies 16 bits of additional message- dependent saroannation 


lParam 
Specifies 32 bits of additional message-dependent information. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also 
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GetCurrentTask, GetMessage, Peek Message 


PostMessage [ax] 


BOOL PostMessage(iwnd, uMsg, wParam, [Param) 


HWND hwnd; 
UINT uMsg; 
WPARAM wParam; 
LPARAM /Param; 


/* handle of the destination window | 
/* message to post */ 
/* first message parameter ia 
/* second message parameter i 


The PostMessage function posts (places) a message in a window’s message queue 
and then returns without waiting for the corresponding window to process the mes- 


~ sage. Messages in a message queue are retrieved by calls to the GetMessage or 


Return Value | 


Comments 


See Also | 


Peek Message function. 


hwnd 
Identifies the window to which the message will be posted. If this parameter is 
HWND_BROADCAST, the message will be posted to all top-level windows, 
including disabled or invisible unowned windows. 


uMsg 
Specifies the message to > be posted. 


wParam 
Specifies 16 bits of additional message-dependent information. 


[Param 
Specifies 32 bits of additional message-dependent information. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


An application should never use the PostMessage function to post a message to a 
control. | 


If the message is being posted to another application and the wParam or [Param 
parameter is used to pass a handle or pointer to a global memory object, the 
memory should be allocated by the GlobalAlloc function, using the 

GMEM_ SHARE flag. | 


| GetMessage, PeekMessage, Post AppMessage, SendDigltemMessage 


Send Message 
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PostQuitMessage Rx] 


void PostQuitMessage(nExitCode) 
int nExitCode; /* exit code */ 


The PostQuitMessage function posts a message to Windows indicating that an ap- 
plication is requesting to terminate execution (quit). This function is typically used 
in response to a WM_DESTROY message. | 


Parameters nExitCode | 
| Specifies an application-defined exit code. It must be the wParam parameter of 
the WM_QUIT message. 


Return Value This function does not return a value. 


Comments The PostQuitMessage function posts a WM_QUIT message to the application 
and returns immediately; the function simply indicates to the system that the appli- 
cation will request to quit some time in the future. 


When the application receives the WM_QUIT message, it should exit the message 
loop in the main function and return control to Windows. 


See Also GetMessage 


PrestoChangoSelector ee 


UINT PrestoChangoSelector(uSourceSelector, uDestSelector) 
UINT uSourceSelector; /* selector to convert a | 
UINT uDestSelector; — /* converted selector (allocated by AllocSelector) i | 


The PrestoChangoSelector function generates a code selector that corresponds to 
a given data selector, or it generates a data selector that corresponds to a given 
code selector. 


An application should not use this function unless it is absolutely necessary, be- 
~ cause its use violates preferred Windows programming practices. | 


Parameters uSourceSelector | 
Specifies the selector to be converted. 


uDestSelector | 
Specifies a selector previously allocated by the AllocSelector function. This 
previously allocated selector receives the converted selector. 


Return Value 


- Comments 


See Also 


PrintDig 
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The return value is the copied and converted selector if the function is successful. 
Otherwise, it is zero. | 


Windows does not track changes to the source selector. Consequently, before any 
memory can be moved, the application should use the converted destination selec- 
tor immediately after it is returned by this function. 


The PrestoChangoSelector function modifies the destination selector to have the 


_ same properties as the source selector, but with the opposite code or data attribute. 


This function changes only the attributes of the selector, not the value of the selec- 
tor. | 


This function was named ChangeSelector in the Windows 3.0 documentation. 


AllocDStoCSAlias, AllocSelector 


#include <commdlg.h> 


BOOL PrintDig(/ppd) 
PRINTDLG FAR* Ippd; /* address of structure with initialization data ) 


Parameters" 


The PrintDlg function displays a Print dialog box or a Print Setup dialog box. The 
Print dialog box makes it possible for the user to specify the properties of a particu- 
lar print job. The Print Setup dialog box makes it possible for the user to select ad- 
ditional job properties and configure the printer. 


lppd , 
Points to a PRINTDLG structure that contains information used to initialize 
the dialog box. When the PrintDlg function returns, this structure contains in- 
formation about the user’s selections. | | 


The PRINTDLG structure has the following form: 


#Hinclude <commdlg.h> 


typedef struct tagPD { /* pd */ 
DWORD 1StructSize; 
HWND hwndOwner; 
HGLOBAL hDevMode; 
HGLOBAL hDevNames; 
HDC hDC; 
DWORD Flags; | 
UINT | nFromPage; 
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Return Value 


Errors 


Example 


UINT nToPage; 
UINT | nMinPage; 
UINT nMaxPage; 
UINT nCopies; 


HINSTANCE hInstance; 
LPARAM 1CustData; 
UINT (CALLBACK* 1 pfnPrintHook) (HWND, UINT, WPARAM, LPARAM) ; 
UINT (CALLBACK* lpfnSetupHook)(HWND, UINT, WPARAM, LPARAM) ; 
LPCSTR ]pPrintTemplateName; 
LPCSTR TpSetupTemplateName; 
HGLOBAL hPrintTemplate; 
HGLOBAL hSetupTemplate; 
} PRINTDLG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if the function successfully configures the printer. The 
return value is zero if an error occurs, if the user chooses the Cancel button, or if 
the user chooses the Close command on the System menu to close the dialog box. 
(The return value is also zero if the user chooses the Setup button to display the 
Print Setup dialog box, chooses the OK button in the Print Setup dialog box, and 
then chooses the Cancel button in the Print dialog box.) 


Use the CommDIgExtendedError function to retrieve the error value, which may 
be one of the following: 


CDERR_FINDRESFAILURE PDERR_CREATEICFAILURE 
CDERR_INITIALIZATION PDERR_DEFAULTDIFFERENT 
CDERR_LOADRESFAILURE PDERR_DNDMMISMATCH 
CDERR_LOADSTRFAILURE PDERR_GETDEVMODEFAIL 
CDERR_LOCKRESFAILURE PDERR_INITFAILURE 


CDERR_MEMALLOCFAILURE PDERR_LOADDRVFAILURE 


CDERR_MEMLOCKFAILURE PDERR_NODEFAULTPRN 


CDERR_NOHINSTANCE ~ PDERR_NODEVICES 
-CDERR_NOHOOK PDERR_PARSEFAILURE | 
CDERR_NOTEMPLATE PDERR_PRINTERNOTFOUND 

CDERR_STRUCTSIZE PDERR_RETDEFFAILURE 


PDERR_SETUPFAILURE 


The following example initializes the PRINTDLG structure, calls the PrintDlig | 
function to display the Print dialog box, and prints a sample page of text if the re- 
turn value is nonzero: 
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PRINTDLG pd; 

/* Set all structure fields to zero. */ 

memset(&pd, @, sizeof(PRINTDLG) ); 

/* Initialize the necessary PRINTDLG structure fields. */ 


pd.IStructSize = sizeof(PRINTDLG); 
pd.hwndOwner = hwnd; 
pd.Flags = PD_RETURNDC; 


/* Print a test page if successful */ 


if (PrintDig(&pd) != @) { . 
Escape(pd.hDC, STARTDOC, 8, “Test-Doc", NULL); 


/* Print text and rectangle */ 


TextOut(pd.hDC, 50, 50, “Common Dialog Test Page", 23); 
Rectangle(pd.hDC, 50, 90, 625, 105); 
Escape(pd.hDC, NEWFRAME, @, NULL, NULL); 
Escape(pd.hDC, ENDDOC, @, NULL, NULL); 
DeleteDC(pd.hDC); 
if (pd.hDevMode != NULL) 
GlobalFree(pd.hDevMode) ; 
if (pd.hDevNames != NULL) 
GlobalFree(pd.hDevNames) ; 
5 
else 
ErrorHandler(); 


ProfClear te =: | 
void ProfClear(void) 


The ProfClear function discards all Microsoft Windows Profiler samples cur- 
_ rently in the sampling buffer. | 


Parameters - This function has no parameters. 
Return Value _ This function does not return a value. 
Comments For more information about using Profiler, see Microsoft Windows Programming 


Tools. 
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Example The following example uses the ProfClear function to clear the Profiler sampling 
buffer before changing the sampling rate: 


ProfClear(); /* clears existing buffer */ 
ProfSampRate(5, 1); /* changes sampling rate */ 


ProfFinish a 


void ProfFinish(void) 


The ProfFinish function stops Microsoft Windows Profiler sampling and flushes 
the output buffer to disk. | 


Parameters _ This function has no parameters. 
Return Value This function does not return a value. 
Comments If Profiler is running in 386 enhanced mode, the ProfFinish function also frees the 


buffer for system use. 


For more information about using Profiler, see Microsoft Windows Programming 
Tools. 


Example The following example uses the ProfFinish function to stop sampling and flush 
the output buffer during WM_DESTROY message processing: 


case WM_DESTROY: 
ProfFinish(); 
PostQuitMessage(Q); 
break; 


ProfFlush 
void ProfFlucsh(void) | 


The ProfFlush function flushes the Microsoft Windows Profiler sampling buffer 
to disk. 


Parameters This function has no parameters. 


Return Value 
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This function does not return a value. 


Comments Excessive use of the ProfFlush function can seriously impair application perform- 
ance. An application should not use ProfFlush when MS-DOS may be unstable 
(inside an interrupt handler, for example). 
For more information about using Profiler, see Microsoft Windows Programming 
Tools. 

Example The following example uses the ProfFlush function to flush the Profiler buffer 
before changing the buffer size: 
ProfFlush(); /* flushes existing buffer a 
ProfSetup(1024, 0); /* uses a 1024K buffer * / 

ProflnsChk 

int ProfinsChk(void) 


Parameters 


Return Value 


Comments 


Example 


The ProfInsChk function determines whether Microsoft Windows Profiler is in- 
stalled. 


This function has no parameters. 


The return value is 1 if Profiler is installed for a mode other than 386 enhanced 
mode, or it is 2 if Profiler is installed for 386 enhanced mode. Otherwise, the re- 
turn value is 0, indicating that Profiler is not installed. 


For more information about using Profiler, see Microsoft Windows Programming 
Tools. 


The following example uses the ProfInsChk function to determine whether the 
Profiler is installed: 


int ick; 
char szMsg[8@]; 
if (Cick = ProfInsChk()) == @) | 


MessageBox(hwnd, "Profiler is not installed!", 
"ProfInsChk", MB_ICONSTOP); | 
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else { 
strcpy(szMsg, "Profiler is installed"); 
if (ick #= 2) { | 
strcat(szMsg, " in 386 enhanced mode"); 
ProfSetup(128, 0); /* uses a 128K buffer */ 
} 
MessageBox(hwnd, szMsg, “ProfInsChk", MB_OK); 


ProfSampRate - 


void ProfSampRate(nRate286, nRate386) 
int nRate286; /* sample rate for non—386 enhanced mode 3 | 
int nRate386; /* sample rate for 386 enhanced mode a 


The ProfSampRate function sets the Microsoft Windows Profiler code-sampling 
rate. | 


— Parameters nRate286 


Specifies the sampling rate if the application is not running in 386 enhanced 
mode. The nRate2&6 parameter can be one of the following values: 


Value Samplingrate 
1 122.070 microseconds 
2 244.141 microseconds 
3 488.281 microseconds 
4 976.562 microseconds 
5 1.953125 milliseconds 
6 3.90625 milliseconds 
7 7.8125 milliseconds 
8 15.625 milliseconds 
9 31.25 milliseconds 

10 62.5 milliseconds 

11 125 milliseconds 

i. * 250 milliseconds 

i3 500 miiiiseconds 


nRate386 | | 
Specifies the sampling rate, in milliseconds if the application is running in 386 
enhanced mode. This value is in the range 1 through 1000. 
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Return Value This function does not return a value. 


Comments Only the rate parameter appropriate to the current mode is used; the other parame- 
ter is ignored. 


The default rate is 2 milliseconds in 386 enhanced mode; in any other mode, the 
value is 5, which specifies a rate of 1.953125 milliseconds. 


For more information about using Profiler, see Microsoft Windows Programming 
Tools. 


Example The following example uses the ProfSampRate function to change the Profiler 
| sampling rate to 1 millisecond in 386 enhanced mode: 


ProfClear(); /* clears existing buffer */ 
ProfSampRate(5, 1); /* changes sampling rate */ 


ProfSetup — 


void ProfSetup(“BufferKB, nSamplesKB) | 
int nBufferKB; /* size of output buffer sg 
— int nSamplesKB; /* amount of sample data written to disk =), 


The ProfSetup function specifies the size of the Microsoft Windows Profiler out- _ 
put buffer and how much sampling data Profiler is to write to the disk. 


Profiler ignores the ProfSetup function when running with Windows in any mode 
other than 386 enhanced mode. 


Parameters nBufferKB 
Specifies the size, in kilobytes, of the eipat buffer. This value i is 1n the range | 
through 1064. The default value 1 is 64. 


nSamplesKB 
Specifies the amount, in kilobytes, of sampling data Profiler writes to the disk. 
A value of zero (the default value) specifies unlimited sampling data. 


Return Value This function does not return a value. 


~ Comments ‘ Do1 not call the ProfSetup function afiet calling ProfStart. To resize memory 
| after ProfStart has been called, first call the ProfStop function. | 


For more information about using Profiler, see M. hes Windows Programming 
Tools. 
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Example 


See Also 


ProfStart 


void ProfStart(void) 


Parameters 
Return Value 


Comments 


Example 


The following example uses the ProfSetup function to set the output buffer size to 
128K if Profiler is installed in 386 enhanced mode: | 


int ick; | 
char szMsg[8Q]; 


if ((ick = ProfInsChk()) == @) 
MessageBox(hwnd, "Profiler is not installed!", 
"ProfInsChk", MB_ICONSTOP); 
else { 
strepy(szMsg, "Profiler is installed"); 
if (ick == 2) { 
strcat(szMsg, " in 386 enhanced mode"); 


ProfSetup(128, @); /* uses a 128K buffer */ 
} 
| MessageBox(hwnd, szMsg, "ProfInsChk", MB_OK); 
J 
ProfStart, ProfStop 


The ProfStart function starts Microsoft Windows Profiler sampling. 
This function has no parameters. 
This function does not return a value. 


For more information about using Profiler, see Microsoft Windows Programming 
Tools. 7 


The following example uses the ProfStart and ProfStop functions to sample 
during the message-queue dispatch process: 


/* Acquire and dispatch messages until WM_QUIT is received. */ 


wnile (GetMessage(&msg, /* message structure * / 
(HWND) NULL, /* handle of window receiving message */ 
Y) /* lowest message to examine - 2 / 


@)) /* highest message to examine * / 
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{ | 
ProfStart(); 
. TranslateMessage(&msg); /* translates virtual-key codes * / 
DispatchMessage(&msg); /* dispatches message to window */ 
— - ProfStop(); 
} : 
See Also ProfStop 


ProfStop - | 
void ProfStop(void) 


The ProfStop function stops Microsoft Windows Profiler sampling. 


Parameters This function has no parameters. 

Return Value This function ie. not return a value. 

Comments For more nfonnacon about using Profiler, see Microsoft Windows Programming 
Tools. 

Example | The following example uses the ProfStart and ProfStop. functions to sample 


during the message-queue dispatch process: 


/* Acquire and dispatch messages until WM_QUIT is received. */ 


while (GetMessage(&msg, /* message structure */ 
| (HWND) NULL, /* handle of window receiving message */ 
Q, /* lowest message to examine * / 
Q)) /* highest message to examine * / 
f | | 


ProfStart(); 


TranslateMessage(&msg); /* translates virtual-key codes x / 
DispatchMessage(&msg); /* dispatches message to window * / 


ProfStop(); 


See Also - ProfStart 
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PtinRect _ 2x | 


BOOL PtInRect(/prc, pt) 
const RECT FAR® (prc; /* address of structure with rectangle **/ 
POINT pt; /* structure with point +) 


The PtInRect function determines whether the specified point lies within a given 
rectangle. A point is within a rectangle if it lies on the left or top side or is within 
all four sides. A point on the right or bottom side is considered outside the 
rectangle. 


Parameters Ipre 
Points to a RECT structure that contains the specified rectangle. The RECT 


structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft wagons Program- 
mer’s Reference, Volume 3. — 
pt ' 
Specifies a POINT structure that contains the specified point. The POINT 
_ Structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value _ The return value is nonzero if the point lies within the given rectangle. Otherwise, 
| it 1S zero. 


See Also — EqualRect, IsRectEmpty 
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PtinRegion _— rex 


BOOL PtInRegion(hrgn, nXPos, nYPos) 


HRGN hrgn; /* handle of region si 
int nXPos; /* x-coordinate of point sa 
int nYPos; /* y-coordinate of point **/ 


The PtInRegion function determines whether a specified point is in the given re- 
gion. | 


Parameters hrgn 
| Identifies the region to be examined. 


nX Pos 
Specifies the logical x-coordinate of the point. — 


nYPos 7 : 
Specifies the logical y-coordinate of the point. 


Return Value The return value is nonzero if the point is in the region. Otherwise, it is zero. 


Example The following example uses the PtInRegion function to determine whether the 
point (50, 50) is in the specified region and prints the result: 


HRGN hrgn; 

BOOL fPtIn; 

LPSTR IpszInRegion = "Specified point is in region."; 

LPSTR IpszNotInRegion = "Specified point is not in region."; 


fPtIn = PtInRegion(hrgn, 50, 5@); 
if (!fPtIn) | 
TextOut(hdc, 10, 10, IpszNotInRegion, 
Tstrilen(1lpszNotInRegion)); 
else | 
TextOut(hdc, 10, 10, IpszInRegion, Istrlen(IpszInRegion)); 


See Also RectInRegion 


PiVisible. Se rex] 
BOOL PtVisible(idc, nXPos, nYPos) ie | 
HDC hdc; —/* handle of device context sf 


int nXPos; /* x-coordinate of point to query */ 
int nYPos; /* y-coordinate of point to query es 


162 PtVisible 


Parameters 


Return Value 


Example 


The PtVisible function determines whether the seeeiied point is within the clip- 
ping region of the given device context. 


hdc 
Identifies the device context. 


nXPos 
Specifies the logical x-coordinate of the point. 


nYPos 
Specifies the logical y-coordinate of the point. 


The return is nonzero if the point is within the clipping region. Otherwise, it is 


ZeTO. 


The following example creates a rectangular region, displays a message inside it, 
and selects the region as the clipping region. The Pt Visible function is used to de- 
termine whether coordinates generated by a double-click are inside the region. If 
so, the message changes to “Thank you.” If not, the CombineRgn function is used 
to create a clipping region that combines the first region with a new region that sur- 
rounds the specified coordinates, and the word “Missed!” is displayed at the 
coordinates. 


HDC hdcLocal; 
HRGN hrgnClick, hrgnMiss, hrgnCombine; 
HBRUSH hbr; 


hdcLocal = GetDC(hwnd); 
hbr = GetStockObject(BLACK_BRUSH) ; 


hrgnClick = CreateRectRgn(9@, 95, 225, 120); 
FrameRgn(hdcLocal, hrgnClick, hbr, 1, 1); 
TextOut(hdcLocal, 100, 100, “Double-click here.", 18); 
SelectClipRgn(hdcLocal, hrgnClick); 


if (PtVisible(hdcLocal, XClick, YClick)) { 
PaintRgn(hdcLocal, hrgnClick); 
FrameRgn(hdcLocal, hrgnClick, hbr, 1, 1); 
~TextOut(hdcLocal, 100, 100, “Thank you.", 10); 
} | 
else if (XClick > @) { 
hrgnMiss = CreateRectRgn(XClick - 5, YClick - 5, XClick + 60, 
YClick + 20); 
hranCombine = CreateRectRan(@. @. @. @): 
CombineRgn(hrgnCombine, hrgnClick, hrgnMiss, RGN_OR); 
SelectClipRgn(hdcLocal, hrgnCombine) ; 
FrameRgn(hdcLocal, hrgnCombine, hbr, 1, 1); 
TextOut(hdcLocal, XClick, YClick, "Missed!", 7); 
} | 


InvalidateRect(hwnd, NULL, FALSE); 
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DeleteObject(hrgnClick); 
DeleteObject(hrgnMiss); 
DeleteObject(hrgnCombine) ; 
ReleaseDC(hwnd, hdcLocal); 


See Also _ CombineRgn, Rect Visible 


QueryAbort Eun 


BOOL QueryAbort(hdc, reserved) 
HDC hdc; /* device-context handle */ 
int reserved; /* reserved; should be zero */ 


The QueryAbort function calls the AbortProc callback function for a printing a0: | 
pacaon and queries whether the printing should be terminated. 


Parameters hdc 
Identifies the device context. 


reserved 
Specifies a reserved value. It should be zero. 


Return Value The return value is TRUE if printing should continue or if there is no abort proce- | 
dure. It is FALSE if the print job should be terminated. The return value is sup- 
plied by the AbortProc callback function. 


See Also | AbortDoc, AbortProc, SetAbortProc 


QuerySendMessage ee SD 


BOOL QuerySendMessage(hreserved], hreserved2, hreserved3, pitessage) 
HANDLE hreserved1; 
HANDLE hreserved2; 


HANDLE hreserved3; - Pts 
LPMSG [pMessage; /* address of structure for message = */ 


The QuerySendMessage function determines whether a message sent by Send- 
Message originated from within the current task. If the message is an intertask - 
message, QuerySend Message puts it into the specified MSG structure. 
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Parameters hreserved1 
Reserved; must be NULL. 


hreserved2 
Reserved; must be NULL. 


hreserved3 
Reserved; must be NULL. 


lpMessage 
Specifies the MSG structure in which to place an intertask message. The MSG 
structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 


DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is zero if the message originated within the current task. Other- 
wise, it is nonzero. 


Comments If the Windows debugger is entering soft mode, the application being debugged 
| should reply to intertask messages by using the ReplyMessage function. 


The NULL parameters are reserved for future use. 


See Also -SendMessage, ReplyMessage 


ReadComm 5 eae rex] 


| int ReadComm(idComDev, IpvBuf, cbRead) 


int idComDev; /* identifier of device to read from Ae ae 
—-2f3A WA MN 7_...N.-L Ike 7A AL... ~f£ Lf A. LA AAA Ltn */ 
vulu TAR” tpVDU] > 7° AUULODSDS VL VUULLUL LULL LUau uy twos io 
int cbRead; /* number of bytes to read *] 


The ReadComm function reads up to a specified number of bytes from the given 
communications device. | 
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Parameters idComDev 
| | Specifies the communications device to be read from. The OpenComm func- 
tion returns this value. 
lpvBuf 
Points to the buffer for the read bytes. 


cbRead 
Specifies the number of bytes to be read. 


Return Value The return value is the number of bytes read, if the function is successful. Other- 
wise, it is less than zero and its absolute value is the number of bytes read. 


For parallel I/O ports, the return value is always zero. 


Comments — When an error occurs, the cause of the error can be determined by using the Get- 
| CommError function to retrieve the error value and status. Since errors can occur 
when no bytes are present, if the return value is zero, the GetCommError func- 
tion should be used to ensure that no error occurred. 


The return value is less than the number specified by the cbRead parameter only if | 
the number of bytes in the receiving queue is less than that specified by cbRead. If 
the return value is equal to cbRead, additional bytes may be queued for the device. 
If the return value is zero, no bytes are present. | 


See Also GetCommError, OpenComm 


RealizePalette 


UINT RealizePalette(hdc) 
HDC hdc; _ _—/* handle of device context */ 


The RealizePalette function maps palette entries from the current ee palette 
to the system palette. 


Parameters hdc | 
ee Identifies the device context containing a logical palette. 


Return Value _ The return value indicates how many entries in the logical palette were mapped to 
different entries in the system palette. This represents the number of entries that 
this function remapped to accommodate changes in the ee palette since the 
logical palette was last realized. : 


766 Rectangle 


Comments 


Example 


See Also 


Rectangle 


A logical color palette acts as a buffer between color-intensive applications and 
the system, allowing an application to use as many colors as necessary without in- 
terfering with either its own displayed color or with colors displayed by other win- 
dows. When a window has the input focus and calls the RealizePalette function, 
Windows ensures that the window will display all the requested colors (up to the 
maximum number simultaneously available on the screen) and Windows displays 
additional colors by matching them to available colors. In addition, Windows 
matches the colors requested by inactive windows that call RealizePalette as 
closely as possible to the available colors. This significantly reduces undesirable 
changes in the colors displayed in inactive windows. 


The following example uses the SelectPalette function to select a palette into a 
device context and then calls the RealizePalette function to map the colors to the 
system palette: 


HPALETTE hpal, hPalPrevious; 

hdc = GetDC(hwnd); 

hPalPrevious = SelectPalette(hdc, hpal, FALSE); 
if (RealizePalette(hdc) == NULL) 


MessageBox(hwnd, "Can't realize palette", "Error", MB_OK); 


ReleaseDC(hwnd, hdc); 


SelectPalette 


BOOL Rectangle(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect) 


HDC hdc; 

int nLeftRect; 
int nTopRect; 
int nRightRect; 
int nBottomRect; 


Parameters 


hdc 


/* handle of device context ay, 
/* x-coordinate upper-left corner *) 
/* y-coordinate upper-left corner 7 
/* x-coordinate lower-right corner sd 
/* y-coordinate lower-right corner =) 


The Rectangle function draws a rectangle, using the current pen. The interior of 


the rectangle is filled by using the current brush. 


Identifies the device context. 


nLeftRect | | a, 
Specifies the logical x-coordinate of the upper-left corner of the rectangle. 
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nlopRect 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the rectangle. 


nBottomRect : | 
Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The figure this function draws extends up to, but does not include, the - 
right and bottom coordinates. This means that the height of the figure is 
nBottomRect — nTopRect and the width of the figure is nRightRect — nLeftRect. 


Both the width and the height of a ner must be greater than 2 units and less 
than 32,767 units. 


Example — The following example uses a RECT structure to store the coordinates used by the 
Rectangle function: 


HDC hdc; 


RECT re = { 10, 10, 180, 140 }; 
Rectangle(hdc, rc.left, rc.top, 
rc.right, rc.bottom); 


See Also PolyLine, RoundRect 


RectinRegion — | ntl 


BOOL RectInRegion(hrgn, [prc) | | 
HRGN hrgn; /* handle of region */ 
const RECT FAR* ies /* address of structure with rectangle 4 


The RectInRegion function determines whether any part of the specified 
rectangle is within the boundaries of the given region. 


Parameters hrgn 
Identifies the region. 
prc 
Points to a RECT structure eoaieiuine thie coordinates of the rectangle. The 
RECT structure has the following form: 
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typedef struct tagRECT { /* rc */ 
int left; | 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if any part of the specified rectangle lies within the 
: boundaries of the region. Otherwise, it is zero. 


Example The following example uses the RectInRegion function to determine whether a 
specified rectangle is in a region and prints the result: 


HRGN hrgn; 

RECT rc = { 100, 10, 130, 5@ }; 

BOOL fRectIn; 

LPSTR IpszOverlap = "Some overlap between rc and region."; 
LPSTR IpszNoOverlap = "No common points in rc and region."; 


fRectIn = RectInRegion(hrgn, &rc); 
if (!fRectIn) 


TextOut(hdc, 10, 10, lpszNoOverlap, Istrlen(1lpszNoOverlap)); 
else 


TextOut(hdc, 10, 10, IpszOverlap, Istrlen(1pszOverlap)); 


See Also PtInRegion 


RectVisible | Ea 


BOOL RectVisible(hdc, prc) 
HDC hdc; /* handle of device context a 
const RECT FAR®* Iprc; /* address of structure with rectangle ws 


The RectVisible function determines whether any part of the specified rectangle 
lies within the clipping region of the given device context. 


Parameters hdc | 
Identifies the device context. 
[pre os , a bee 
Points to a RECT structure that contains the logical coordinates of the specified 
_ rectangle. The RECT structure has the following form: 


Return Value 


Example 


See Also 
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typedef struct tagRECT t /* ro */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the a Windows Program- 
mer’s Reference, Volume 3. 


The return value is nonzero if some portion of the rectangle is within the clipping 
region. Otherwise, it is zero. 


The following example paints a clipping region yellow by painting the client area. 
The Rect Visible function is called to determine whether a specified rectangle over- 
laps the clipping region. If there is some overlap, the rectangle is filled by using a 
red brush. If there is no overlap, text is displayed inside the clipping region. In this. 
case, the rectangle and the region do not overlap, even though they both specify 
110 as a boundary on the y-axis, because regions are defined as including the pix- 
els up to but not including the specified right and bottom coordinates. 


RECT rc, rcVis; 
HRGN hrgn; 
HBRUSH hbrRed, hbrYellow; 


GetClientRect(hwnd, &rc); 
hrgn = CreateRectRgn(10, 10, 310, 110);- 
SelectClipRgn(hdc, hrgn); 


hbrYellow = CreateSolidBrush(RGB(255, 255, @)); 
FillRect(hdc, &rc, hbrYellow);. 


SetRect(arcVis, 10, 110, 310, 300); 


if (RectVisible(hdc, &rcVis)) { 


hbrRed = CreateSolidBrush(RGB(255, @, @)); 
FillRect(hdc, &rcVis, hbrRed); 
DeleteObject(hbrRed) ; 


} 
else { | 
SetBkColor(hdc, RGB(255, 255, @)); | 
TextOut(hdc, 20, 5@, "Rectangle outside clipping region.", 34); 
} ne 


DeleteObject(hbrYellow); 
DeleteObject(hrgn); 


CreateRectRgn, PtVisible, SelectClipRgn 


770 RedrawWindow 


RedrawWindow 


BOOL RedrawWindow(hwnd, lprcUpdate, hrgnUpdate, fuRedraw) 


HWND hwnd; /* handle of window a 
const RECT FAR* [prcUpdate; —_‘/* address of structure with update rect. i 
HRGN hrgnUpdate; /* handle of update region sa 
UINT fuRedraw; /* redraw flags _ sy 
The RedrawWindow function updates the specified rectangle or region in the 
given window’s client area. 
' Parameters hwnd 


Identifies the window to be redrawn. If this parameter is NULL, the desktop 
window is updated. 


[prc Update 
Points to a RECT structure sone ine the coordinates of the update rectangle. 
This parameter is ignored if the hrgnUpdate parameter contains a valid region 
handle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc x*/ 
int left; 
int top; 
int right; 

| int bottom; 

} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hrgnUpdate 
Identifies the update region. If both the hrgnUpdate and IprcUpdate parameters 
are NULL, the entire client area is added to the update region. 


juRedraw 
Specifies one or more redraw flags. This parameter can be a combination of 
flags: 


The following flags are used to invalidate the window: 
Value | Meaning 


RDW_ERASE Causes the window to receive a 
| WM_ERASEBKGND message when the window is 


renointed Tho RDW_ INIWAT TT) ATE flac muet alen 
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be specified; otherwise, RDW_ERASE has no effect. 


Value 


RDW_FRAME — 
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Meaning 


Causes any part of the non-client area of the window 
that intersects the update region to receive a 
WM_NCPAINT message. The RDW_INVALIDATE 
flag must also be specified; otherwise, _ | 
RDW_FRAME has no effect. The WM_NCPAINT 
message is typically not sent during the execution 

of the Redraw Window function unless either 


_ RDW_UPDATENOW or RDW_ERASENOW is 


RDW_INTERNALPAINT 


RDW_INVALIDATE 


specified. 
Causes a WM_PAINT message to be posted to the 


- window regardless of whether the window contains 


an invalid region. 


Invalidate [IprcUpdate or hrgnUpdate (only one may 
be non-NULL). If both are NULL, the entire win- 
dow is invalidated. 


The following flags are used to validate the window: 


Value 


RDW_NOERASE 


RDW_NOFRAME 


RDW_NOINTERNALPAINT 


RDW_VALIDATE 


Meaning 


Suppresses any pending WM_ERASEB KGND 
messages. 


Suppresses any pending WM_NCPAINT 
messages. This flag must be used with 
RDW_VALIDATE and is typically used with 
RDW_NOCHILDREN. This option should be 
used with care, as it could cause parts of a win- 
dow from painting properly. 

Suppresses any pending internal WM_PAINT 
messages. This flag does not affect WM_PAINT 
messages resulting from invalid areas. | 
Validates IprcUpdate or hrgnUpdate (only one 
may be non-NULL). If both are NULL, the entire 
window is validated. This flag does not affect in- 
ternal WM_PAINT es ca . 


The following flags control when repainting occurs. No painting is performed 
by the RedrawWindow function unless one of these bits is specified. 


Value Meaning 


RDW_ERASENOW Causes the affected windows (as specified by the 
| RDW_ALLCHILDREN and RDW_ _~NOCHILDREN 
flags) to receive WM_NCPAINT and 
WM_ERASEBKGND messages, if necessary, before 
the function returns. WM_PAINT messages are deferred. 
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Value | Meaning 

RDW_UPDATENOW Causes the affected windows (as specified by the 
RDW_ALLCHILDREN and RDW_NOCHILDREN 
flags) to receive WM_NCPAINT, 
WM_ERASEBKGND, and WM_PAINT messages, 
if necessary, before the function returns. 


By default, the windows affected by the RedrawWindow function depend on 
whether the specified window has the WS_CLIPCHILDREN style. The child 
windows of WS_CLIPCHILDREN windows are not affected; however, non- 
WS_CLIPCHILDREN windows are recursively validated or invalidated until a 
WS_CLIPCHILDREN window is encountered. The following flags control 
which windows are affected by the Redraw Window function: 


Value Meaning 
RDW_ALLCHILDREN _Includes child windows, if any, in the repainting 
operation. | 
RDW_NOCHILDREN Excludes child windows, if any, from the repainting 
operation. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments When the RedrawWindow function is used to invalidate part of the desktop win- 


dow, the desktop window does not receive a WM_PAINT message. To repaint the 
desktop, an application should use the RDW_ERASE flag to generate a 
WM_ERASEBKGND message. 


See Also - GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, 
_ UpdateWindow 


RegClosekey [aa 
#include <shellapi.h> 


LONG RegCloseKey(hkey) | 
HKRY hkev: /* handle of kev ta clase */ 


—~ ~~ em 


The RegCloseKey function closes a key. Closing a Key releases the key’s handle. 
When all keys are closed, the registration database is updated. 


Parameters 7 hkey | 
| Identifies the open key to close. 
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Return Value The return value is ERROR _ SUCCESS if the function is successful. Otherwise, it 
is an error value. 


Comments The RegCloseKey function should be called only if a key has been opened by 
| either the RegOpenKey function or the RegCreateKey function. The handle for a 
given key should not be used after it has been closed, because it may no longer be 
valid. Key handles should not be left open any longer than necessary. 


Example | The following example uses the RegCreateKey function to create the handle of a 
protocol, uses the RegSet Value function to set up the subkeys of the protocol, and 
then calls RegCloseKey to save the information in the database: 


HKEY hkProtocol; 


if (RegCreateKey(HKEY_CLASSES_ ROOT, | /* root | 7) 
“NewAppDocument\\protocol\\StdFileEditing", /* protocol string */ 
&hkProtocol) != ERROR_SUCCESS) /* protocol key handle */ 

return FALSE; 

RegSetValue(hkProtocol, /* handle of protocol key a * / 
"server", /* name of subkey * / 
REG_SZ, /* required * / 
“"newapp.exe", - /* command to activate server * / 
10); /* text string size * / 

RegSetValue(hkProtocol, /* handle of protocol key */ . 
"verb\\o", | | /* name of subkey - Per.) aoe 
REG_SZ, /* required | | * / 
"EDIT", |  /* server should edit object * / 
4); /* text string size ae / 

RegCloseKey(hkProtocol); /* closes protocol key and subkeys * / 

See Also RegCreateKey, RegDeleteKey, RegOpenKey, RegSetValue 


RegCreateKey = ae Ga 


#include <shellapi.h> 

LONG RegCreateKey(hkey, IpseSubKey, [phkResult) : - 
HKEY hkey; /* handle of an open key | a ie 
LPCSTR IpszSubKey; _ /* address of string for subkey to open fale 


HKEY FAR* IphkResult; /* address of handle of open key ie 
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Parameters 


Return Value 


Comments 


Example 


The RegCreateKey function creates the specified key. If the key already exists in 
the registration database, RegCreateKey opens it. 


hkey 
Identifies an open key (which can be HKEY_CLASSES_ROOT). The _ 
opened or created by the RegCreateKey function is a subkey of the key iden- 
tified by the hkey parameter. This value should not be NULL. 

IpszSubKey 
Points toa null-terminated string Spectyine the Sey to open or create. 


[phkResult 
Points to the handle of the key that is opened or created. 


The return value is ERROR SUCCESS if the function is successful. Otherwise, it 
is an error value. 


An application can create keys that are subordinate to the top level of the database 
by specifying HKEY_CLASSES_ROOT for the hKey parameter. An application 
can use the RegCreateKey function to create several keys at once. For example, 
an application could create a subkey four levels deep and the three preceding sub- 
keys by specifying a string of the following form for the /pszSubKey parameter: 


subkey]\subkey2\subkey3\subkey4 


The following example uses the RegCreateKey function to create the handle of a 
protocol, uses the RegSetValue function to set up the subkeys of the protocol, and 
then calls RegCloseKey to save the information in the database: 


HKEY hkProtocol; 


if (RegCreateKey(HKEY_CLASSES_ ROOT, /* root * / 


"NewAppDocument\\protocol\\StdFileEditing", /* protocol string */ 
&hkProtocol) != ERROR_SUCCESS) /* protocol key handle */ 
return FALSE; 

RegSetValue(hkProtocol, /* handle of protocol key * / 
"server", _/* name of subkey * / 
REG_SZ, ! _ /* required * / 
"newapp.exe", /* command to activate server a / 
10); /* text string size * / 

RegSetValue(hkProtocol, /* handle of protocol key a / 
"verb\\O", | /* name of subkey * / 
REG_SZ, /* required x / 
"EDIT",  /* server should edit object * / 
4); /* text string size * / 


RegCloseKey(hkProtocol ); /* closes protocol key and subkeys + / 


- RegDeleteKey 115 


See Also | RegCloseKey, RegOpenKey, RegSetValue 


RegDeleteKey : aa 


#include <shellapi.h> 

LONG RegDeleteKey(hkey, IpszSubKey) 

HKEY hkey; /* handle of an open key oy] 
~LPCSTR IpszSubKey; /* address of string for subkey to delete sid 


The RegDeleteKey function deletes the specified key. When a key i is deleted, its 
value and all of its subkeys are deleted. 


Parameters hkey 


Identifies an open key (which can be HKEY_CLASSES ROOD. The key de- 
leted by the RegDeleteKey function is a subkey of this key. 


lpszSubKey 
Points to a null-terminated string specifying the subkey to delete. This value 
should not be NULL. 


Return Value The return value is ERROR SUCCESS if the function is : successful: Otherwise, it 
is an error value. 


If the error value is ERROR_ ACCESS _DENIED, either the application d does not 
have delete privileges for the specified key or another application has opened the 
specified Key. 


Example. The following example uses the RegQueryValue function to retrieve the name of 
| an object handler and then calls the RegDeleteKey function to delete the key if its 
_ Value is nwappobj.dll: 


char Ser ure Eeeys 
LONG cb; 
~ HKEY hkStdFileEditing: 


if (RegOpenKey(HKEY_CLASSES_ROOT, 
"NewAppDocument\\protocol\\StdFileEditing", 
— &hKStdFileEditing) == ERROR_SUCCESS) { 


cb = sizeof(szBuff): 
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See Also 


RegEnumKey 


if (RegQueryValue(hkStdFileEditing, 
"handler", 
szBuff, 
&cb) == ERROR_SUCCESS | 
&& Istrcmpi("nwappobj.d11", szBuff) == @) 
RegDeleteKey(hkStdFileEditing, “handler™); 
RegCloseKey(hkStdFileEditing) ; 


RegCloseKey 


#include <shellapi.h> 


LONG RegEnumKey(hkey, iSubkey, IpszBuffer, cbBuffer) 


HKEY hkey; 
DWORD iSubkey; 
LPSTR I[pszBuffer; 
DWORD cbBuffer; 


Parameters 


Comments 


/* handle of key to query | sa 
/* index of subKey to query st | 
/* address of buffer for subkey string si 
/* size of subkey buffer | 


The RegEnumKey function enumerates the subkeys of a specified key. 


hkey | 7 
Identifies an open key (which can be HKEY_CLASSES_ROOT) for which sub- 
key information is retrieved. 

iSubkey 
Specifies the index of the subkey to retrieve. This value should be zero for the 
first call to the RegEnumKey function. 

lpszBuffer 
Points to a buffer that contains the name of the subkey when the function 
returns. This function copies only the name of the subkey, not the full key 
hierarchy, to the buffer. 

cbBuffer | 3 
Specifies the size, in bytes, of the buffer pointed to by the /pszBuffer parameter. 


POL. wae 21. fe TNNMND ATIMOTMOAG [41.2 fat fe eee AL ND et tk 
LLC LULULIT Value ls DININVIAN_VDULLU DS) LL UIC LULICULUIL IS SULLOUSSIUL. ULLICL Wise, it 
is an error value. 


The first parameter of the RegEnumKey function must specify an open key. Ap- 
plications typically precede the call to the RegEnumKey function with a call to 
the RegOpenKey function and follow it with a call to the RegCloseKey function. 
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Calling RegOpenKey and RegCloseKey is not necessary when the first parameter © 
is HKEY_CLASSES_ROOT, because this key is always open and available; how- 
ever, calling RegOpenKey and RegCloseKey in this case is a time optimization. 
While an application is using the RegEnumKey function, it should not make calls © 
to any registration functions that might change the key being queried. 


To enumerate subkeys, an application should initially set the iSubkey parameter to 
zero and then increment it on successive calls. 


Example The following example uses the RegEnum Key function to put the values associ- 
ated with top-level keys into a list box: 


HKEY hkRoot; 

char szBuff[80], szValue[80]; 
static DWORD dwIndex; 

LONG cb; 


if (RegOpenKey(HKEY_CLASSES_ROOT, NULL, &hkRoot) == ERROR_SUCCESS) { 
for (dwindex = @; RegEnumKey(hkRoot, dwindex, szBuff, 
a resortezuit)) == ERROR SUCCESS; ++dwIndex) { 
if (*szBuff = *) 
sont inuel. 
cb = sizeof(szValue); 
if (RegQueryValue(hkRoot, (LPSTR) szBuff, szValue, 
&cb) == ERROR_SUCCESS) 
SendDigItemMessage(hDlg, ID_ENUMLIST, LB_ADDSTRING, @, 
i (LONG) (LPSTR) szValue); | 


} 
RegCloseKkey(hkRoot) ; 


See Also RegQueryValue 


RegisterClass Pax] 


ATOM RegisterClass(Ipwc) 
const WNDCLASS FAR* Ipwc; /* address of structure with class data eee OL 


The RegisterClass function registers a window class for subsequent use in calls to 
the CreateWindow or CreateWindowEx function. 


Parameters — lpwc | . 
Points to a WNDCLASS structure. The structure must be filled with the. appro- 
priate class attributes before being passed to the function, The WNDCLASS 
structure has the following form: 
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Return Value 


Comments 


Example 


| -we.style 


typedef struct tagWNDCLASS { /* wo */ 


UINT style; 
WNDPROC ¥ IpfnWndProc; 
int. cbClsExtra; 
int cbWndExtra; 
HINSTANCE hInstance; 
HICON hIcon; 


HCURSOR  hCursor; 

HBRUSH hbrBackground; 

LPCSTR lpszMenuName; 

LPCSTR IpszClassName; 
} WNDCLASS; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


_ The return value is an atom that uniquely identifies the class being registered. For 


Windows versions 3.0 and earlier, the return value is nonzero if the function is 
successful or zero if an error occurs. 


An application cannot register a global class if either a global class or a task- 
specific class already exists with the given name. 


An application can register a task-specific class with the same name as a global 
class. The task-specific class overrides the global class for the current task only. A 
task cannot register two local classes with the same name. However, two different 
tasks can register task-specific classes using the same name. 


The following example registers a window class, then creates a window of that 
class: 


WNDCLASS we; 

HINSTANCE hinst; 

char szMyClass[] = "MyClass"; 
HWND hwndMyWindow; | 


/* Register the window class. */ 


Q: 


(HBRUSH) (COLOR_WINDOW + 1); 
(LPCSTR) NULL; 
szMyClass; | 


wc. hbrBackground 
wc.]pszMenuName 
wc.IlpszClassName 


wce.IlpfnWndProc = MyWndProc; 

wce.cbClsExtra = Qs; — 

wce.cbWndExtra = Q; 

wc. hInstance = hinst; 

we .hTcon = |LoadTcon(hinst, "MvIcon"): 
wce.hCursor = LoadCursor(NULL, IDC_ARROW); 


See Also 
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if (!RegisterClass(&wc)) 
return FALSE; 


/* Create the window. */ 


hwndMyWindow = CreateWindow(szMyClass, "MyApp”, 
WS_OVERLAPPED | WS_SYSMENU, CW_USEDEFAULT, @, 
CW_USEDEFAULT, @, NULL, NULL, | 
hinst, NULL ); 


CreateWindow, CreateWindowEx, GetClassInfo, GetClassName, PE ANCEISNEL- 
Class, WindowProc 


RegisterClipboardFormat — : ex] 


UINT RegisterClipboardFormat(/pszFormatName) 
LPCSTR /pszFormatName; /* address of name string —_ */ 


Parameters 


Return Value 


Comments 


See Also 


The RegisterClipboardFormat function registers a new clipboard format. The 


registered format can be used in subsequent clipboard functions as a valid format 
in which to render data, and it a appear in nine cupboanis list 2 formats. 


ipscF pimaivaae , | 
Points to a null- terminated ee that names the new format. 


The return value indicates the newly registered fori: If the identical format 


name has been registered before, even by a different application, the format’s refer- 
ence count is incremented (increased by one) and the same value is returned as 
when the format was originally registered. The return value is zero if the format 
cannot be registered. 


The format value returned by the RegisterClipboardFormat function is within 
the range 0xC000 through OxFFFF. 


CountClipboardFormats, EnumClipboardFormats, GetClipboardFormat- 


Name, GetPriorityClipboardFormat, IsClipboardFormatAvailable 
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RegisterWindowMessage — [2x] 


UINT RegisterWindowMessage(/psz) 
LPCSTR Ipsz;__—s/* address of message string */ 


The RegisterWindowMessage function defines a new window message that is 
guaranteed to be unique throughout the system. The returned message value can 
be used when calling the SendMessage or PostMessage function. 


Parameters Ipsz 
Points to a null-terminated string that specifies the message to be registered. 


Return Value The return value is an unsigned short integer in the range 0xC000 through OxXFFFF 
if the message is successfully registered. Otherwise, the return value is 0. 


Comments Register WindowMessage | is typically used to register messages for communicat- 
ing between two cooperating applications. 


If two different applications register the same message string, the applications re- 
turn the same message value. The message remains registered until the Windows 
session ends. 


Use the Register WindowMessage function only when more than one application 
must process the same message. For sending private messages within a window 
class, an application can use any integer in the range WM_USER through Ox7FFF. 
(Messages in this range are private to a window class, not to an application. For ex- 
ample, such predefined control classes as BUTTON, EDIT, LISTBOX, and 
COMBOBOX may use values in this range.) 


‘See Also 7 PostAppMessage, PostMessage, SendMessage 


RegOpenKey | [3.1 | 
#include <shellapi.h> | 
LONG RegOpenKey(hkey, IpszSubKey, iphkResult) 


FINELY nkey; _ /* handie of an open key **/ 
LPCSTR IpszSubKey; /* address of string for subkey to open of 
HKEY FAR®* [phkResult; /* address of handle of open key **/ 


The RegOpenKey function opens the specified key. 
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Parameters — hkey 

| Identifies an open key (which can be HKEY_ CLAS SES_ROOT). The key 
opened by the RegOpenKey function is a subkey of the key identified Py this 
parameter. This value should not be NULL. 


IpszSubKey 
Points to a null-terminated string specifying the name of the subkey to open. 


[phkResult 
Points to the handle of the key that is opened. 


Return Value | The return value is ERROR _ SUCCESS if the function is successful. Otherwise, it 
is an error value. 


Comments Unlike the RegCreateKey function, the RegOpenKey function does not create 
the specified key if the key does not exist in the database. 


Example The following example uses the RegOpenKey function to retrieve the handle of 
| the StdFileEditing subkey, calls the RegQuery Value function to retrieve the name 
of an object handler, and then calls the RegDeleteKey function to delete the key if 
its value is nwappobj.dll: 


char szBuff[80]; 
LONG cb; 
HKEY hkStdFileEditing; 


if  CRegOpenKey(HKEY_ CLASSES_ROOT, 
"NewAppDocument\\protocol\\StdFileEditing", 
&hkStdFileEditing) == ERROR_SUCCESS) { 


cb = sizeof(szBuff); 
if PREG RUE Ya UC IRS EE TA Near EIN gs 
"handler", 
szBuff, 
&cb) == ERROR_SUCCESS | 
&& Istrcmpi("nwappobj.d11", szBuff) == @) © 
RegDeleteKey(hkStdFileEditing, “handler™); 
RegCloseKey(hkStdFileEditing); 
—S 


See Also RegCreateKey 
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RegQueryValue 


#include <shellapi.h> 


LONG RegQueryValue(hkey, lpszSubKey, lpszValue, lpcb) 


HKEY hkey; /* handle of key to query _ sy 
LPCSTR [pszSubKey; /* address of string for subkey to query */ 
LPSTR IpszValue; /* address of buffer for returned string */ 
LONG FAR* Ipcb; /* address of buffer for size of returned string i 
The RegQueryValue function retrieves the text string associated with a specified 
key. 
Parameters hkey 


Return Value 


Example | 


Identifies a currently open key (which can be HKEY_CLASSES_ROOT). This 
value should not be NULL. 


lpszSubKey 


Points to a null-terminated string specifying the name of the subkey of the hkey 
parameter for which a text string is retrieved. If this parameter is NULL or 
points to an empty string, the function retrieves the value of the hkey parameter. 


lpszValue 
Points to a buffer that contains the text string when the function returns. | 

lpcb 
Points to a variable specifying the size, in bytes, of the buffer pointed to by the 
[pszValue parameter. When the function returns, this variable contains the size 
of the string copied to /pszValue, including the null-terminating character. 


The return value is ERROR SUCCESS if the function is successful. Otherwise, it 
is an error value. 


The following example uses the RegOpenKey function to retrieve the handle of 
the StdFileEditing subkey, calls the RegQuery Value function to retrieve the name 


of an object handler and then calls the RegDeleteKey function to delete the key if 


its value is nwappobj.dll: 


char szBuff[8@]; 
LONG cb; 
HKEY hkStdFileEditing; 


if (Raa qOne nKav(HKEV_ CLASSES BOOT, 


"NewAppDocument\\protocol\\StdFileEditing", 
&hkStdFileEditing) == ERROR_SUCCESS) { 


cb = sizeof(szBuff); 


See Also 


RegSetValue 
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if (RegQueryValue(hkStdFileEditing, 
"handler", 
szBuff, 
&cb) == ERROR_SUCCESS 
&& Istrcempi("nwappobj.d11", szBuff) == @) 
RegDeleteKey(hkStdFileEditing, “hand her") 5 
RegCloseKey(hkStdFileEditing) ; 


RegEnumKey 


#include <shellapi.h> 
LONG RegSetValue(hkey, IpszSubKey, fdwType, lpszValue, cb) 


HKEY hkey; /* handle of key **/ 
LPCSTR [pszSubKey; /* address of string for subkey */ 
DWORD fdwType; /* must be REG_SZ a 
LPCSTR IpszValue; — /* address of string for key ei] 
DWORD cb; /* ignored */ 
The RegSetValue function associates a text string with a specified key. 
Parameters hkey 


Return Value 


Identifies a currently open ey (which can be HKEY_CLASSES_ROOT). This 
value should not be NULL. 


[pszSubKey 
Points to a null-terminated string specifying the subkey of the hkey parameter 
with which a text string is associated. If this parameter is NULL or points to an 
empty string, the function sets the value of the hkey parameter. | 


fdwType 
Specifies the string type. For Windows version 3.1, this value must be REG_SZ. 
IpszValue 
Points to a ull’ terminated string specifying the text string to set for the given 
Key. 
cb | | | | | 
Specifies the size, in bytes, of the string pointed to by the /pszValue parameter. 
For ngOws version 3.1, this value isignored. _ 


The return value is ERROR_SUCCESS if the function i is successful. Otherwise, it 
is an error value. 


784 ReleaseCapture 


Comments 


Example 


See Also 


If the key specified by the IpszSubKey parameter does not exist, the RegSet Value 


function creates it. 


The following example uses the RegSet Value function to register a filename ex- 
tension and its associated class name: 


RegSetValue(HKEY_CLASSES_ ROOT, 
are 0.0 cua 
REG_SZ, 
"NewAppDocument", 
14); 


RegSetValue(HKEY_CLASSES_ ROOT, 
"NewAppDocument", 
REG_SZ, 
"New Application", 
15); 


RegCreateKey, RegQuery Value 


ReleaseCapture | 


void ReleaseCapture(void) 


Parameters 
Return Value 
Comments 


See Also 


/* 
/* 


root 

string for filename extension 
required 

class name for extension 

size of text string 


root 

string for class-definition key 
required | 

text description of class 

size of text string 


* / 
* / 
* / 
* / 
* / 


* / 
* / 
ef 
* / 
* / 


[2x] 


The ReleaseCapture function releases the mouse capture and restores normal 
input processing. A window with the mouse capture receives all mouse input re- 
gardless of the position of the cursor. 


This function has no parameters. 


This function does not return a value. 


An application calls this function after calling the SetCapture function. 


SetCapture | 
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ReleaseDC [2x | 


int ReleaseDC(hwnd, hdc) 
HWND hwnd; /* handle of window with device context */ 
HDC hdc; /* handle of device context */ 


_ The ReleaseDC function releases the given device context, freeing it for use by 
other applications. 


Parameters hwnd 
Identifies the window whose device context is to be released. 


hdc 
Identifies the device context to be released. 


Return Value The return value is 1 if the function is successful. Otherwise, it is O. 


~ Comments The effect of ReleaseDC depends on the type of device context. It frees only com- 
-mon and window device contexts. It has no effect on class or private device con- 
texts. 


The application must call the ReleaseDC function for each call to the Get- 
WindowDC function and for each ci to the GetDC function that retrieves a com- 
mon device context. 


See Also _ BeginPaint, EndPaint, GetDC, GetWindowDC 


RemoveFontResource ‘Gola ee 


BOOL RemoveF ontResource(lpszFile) | | 
LPCSTR IpszFile; /* address of string for filename of | 


The RemoveFontResource function removes an added font resource from the 
specified file or from the Windows font table. 


Parameters _. IpszFile 
Points to a string that names the font resource file or contains a handle of a 
loaded module. If this parameter points to the font resource file, the string must 
be null-terminated and have the MS-DOS filename format. If the parameter con- 
tains a handle, the handle must be in the low- order word and the high-order 
word must be Zero. | 
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Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. — 


Comments Any application that adds or removes fonts from the Windows font table should 
| send a WM_FONTCHANGE message to all top-level windows in the system by 
using the SendMessage function with the hwnd parameter set to OXFFFF. 


In some cases, the RemoveFontResource function may not remove the font re- 
source immediately. If there are outstanding references to the resource, it remains 
loaded until the last logical font using it has been removed (deleted) by using the 
DeleteObject function. | 


Example The following example uses the AddFontResource function to add a font re- 
source from a file, notifies other applications by using the SendMessage function, 
then removes the font resource by calling the RemoveFontResource function: 


AddFontResource("fontres.fon"); 
SendMessage(HWND_ BROADCAST, WM_FONTCHANGE, @, @); 


. /* Work with the font. */ 


if (RemoveFontResource("fontres.fon")) { 
SendMessage(HWND_ BROADCAST, WM_FONTCHANGE, @, @); 
return TRUE; 

} 

else 
return FALSE; 


See Also AddFontResource, DeleteObject, SendMessage 


RemoveMenu | 


BOOL RemoveMenu(hmenu, idItem, fuF lags) 
HMENU hmenu; /* handle of menu’ 

UINT idltem; /* menuitem todelete */ 
UINT fuFlags; /* menu flags ye 


The RemoveMenu function deletes a menu item with an associated pop-up menu 
from a menu but does not destroy the handle of the pop-up menu, allowing the 
menu to be reused. Before calling this function, an application should call the Get- 
‘SubMenu function to retrieve the pop-up menu handle. 


Parameters = = = hmenu 
Identifies the menu to be changed. 
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idItem 
Specifies the menu item to be removed, as determined by the fuFlags parameter. 


fuFlags 
Specifies how the id/tem parameter is to be Satie This parameter can be 
one of the following values: 


Value Meaning | , 
MF_BYCOMMAND The idltem parameter specifies the menu-item identifier. 
MF_BYPOSITION The idltem parameter specifies the zero-based position of 


the menu item. 


Return Value The return value is nonzero if the function is successful. ae it is zero. 


- Comments Whenever a menu changes (whether or not it is in a window that 1 1S displayed), t the 
application should call the DrawMenuBar function. 


See Also AppendMenu, CreateMenu, DeleteMenu, DrawMenuBar, GetSubMenu, 
InsertMenu 


RemoveProp oe 7 (ea 


HANDLE RemoveProp(hwnd, Ipsz) 
HWND hwnd; = /*handle of window | ep 
LPCSTR Ipsz;__—_—s/* atom or address of string 7) 


The RemoveProp function removes an entry font t the property list of the given 
window. The RemoveProp function returns a data handle so that the application 
can free the data associated with the handle. 


Parameters hwnd 
Identifies the window whose property list is to be changed. 


Ipsz a 
Points to a null-terminated string or an atom that identifies a string. If an atom. 
is given, it must be a global atom created by a previous call to the GlobalAdd- 
Atom function. The atom, a 16-bit value, must be placed in the low-order word 
of this parameter; the high-order word must be zero. 


Return Value The return value is the handle of the given string if the function is successful. 
| | Otherwise, it is NULL—for example, if the string cannot be found in the given | 
property list. | | 


788 ReplaceText 


Comments An application can remove only those properties it has added. It should not re- 
| move properties added by other applications or by Windows itself. 


An application must free the data handles associated with entries removed from a 
property list. The application should remove only those properties it added to the 
property list. | | 


See Also | GetProp, GlobalAddAtom 


ReplaceText = EXE 


#include <commdlg.h> 


HWND ReplaceText(ipfr) 
FINDREPLACE FAR? lpfr; /* address of structure with initialization data */ 


The ReplaceText function creates a system-defined modeless dialog box that _ 
makes it possible for the user to find and replace text within a document. The ap- 
plication must perform the actual find and replace operations. 


Parameters Ipfr 


Points to a FINDREPLACE structure that contains information used to initial- 
ize the dialog box. When the user makes a selection in the dialog box, the sys- 
tem fills this structure with information about the user’s selection and then 


sends a message to the application. This message contains a pointer to the 
FINDREPLACKE structure. 


The FINDREPLACE structure has the following form: 


#Finclude <commdlg.h> 


typedef struct tagFINDREPLACE { /* fr */ 


DWORD 1StructSize; 
HWND hwndOwner; 
HINSTANCE hInstance; 
DWORD Flags; 
LPSTR TpstrFindWhat; 
LPSTR IpstrReplaceWith; 
UINT — wFindWhatLen; 
UINT  wReplaceWithLen; 
LPARAM ~~ 1ICustData; | 
—UINT (CALLBACK* IpfnHook)(HWND, UINT, WPARAM, LPARAM); 


LPCSTR lpTemplateName; 
} FINDREPLACE; 


Return Value 


Errors 


Comments 


Example 
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For a full description of this structure, see the M icrosoft Windows Program- 
mer’ s SI ICIENCG, Volume 3. 


The return value is the window handle of the dialog box, or it is NULL if an error 
occurs. An application can use this handle to communicate with or to close the 
dialog box. 


Use the CommDlgExtendedError function to retrieve the error value, which may 
be one of the following: 


CDERR_FINDRESFAILURE 
CDERR_INITIALIZATION 


~CDERR_LOADRESFAILURE 


CDERR_LOADSTRFAILURE 
CDERR_LOCKRESFAILURE 
CDERR_MEMALLOCFAILURE 
CDERR_MEMLOCKFAILURE 
CDERR_NOHINSTANCE 
CDERR_NOHOOK 
CDERR_NOTEMPLATE 
CDERR_STRUCTSIZE 

FRERR “BUFFERLENGTHZERO > 


The dialog box procedure for the ReplaceText function passes user requests to the 
application through special messages. The /Param parameter of each of these mes- 
sages contains a pointer to a FINDREPLACE structure. The procedure sends the 


_ messages to the window identified by the hwndOwner member of the FIND- | 


REPLACE structure. An application can register the identifier for these messages 
by specifying the commdlg_FindReplace string in a call to the mee en GON: | 
Message function. 


For the TAB Key to function correctly, any application that calls the ReplaceText 
function must also call the IsDialogMessage function in its main message loop. 
(The IsDialogMessage function returns a value that indicates whether messages 


are intended for the Replace dialog box.) 


This example initializes a FINDREPLACE structure e and calls the ReplaceT ext 
function to display the Replace dialog box: | 


static FINDREPLACE fr; | | 3 
char szFindWhat[256] = ""; /* string to find * / 
char szReplaceWith[256] = ""; /* string to replace */ 


/* Set all structure fields to zero. */ 


-memset(&fr, @, sizeof(FINDREPLACE) ); 
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fr.1StructSize = sizeof(FINDREPLACE) ; 
fr.hwndOwner = hwnd; 

fr.lpstrFindWhat = szFindWhat; 
fr.wFindWhatLen = sizeof(szFindWhat); 


fr.ipstrReplaceWith = szReplaceWith; 


See Also 


fr.wReplaceWithLen = sizeof(szReplaceWith); 


hDlg = ReplaceText(&fr); 


In addition to initializing the members of the FINDREPLACKE structure and 
calling the ReplaceText function, an application must register the special 
FINDMSGSTRING message and process messages from the dialog box. Refer to 
the description of the FindText function for an example that shows how an appli- 
cation registers and processes a message. 


FindText, IsDialogMessage, Register WindowMessage 


-ReplyMessage [2x | 


void ReplyMessage(/Result) 


LRESULT /Result; 


Parameters 


Return Value 


Comments 


/* message-dependent reply sy | 


The ReplyMessage function is used to reply to a message sent through the Send- 
Message function without returning control to the function that called Send- 
Message. 


[Result 
Specifies the result of the message processing. The possible values depend on 
the message sent. 


This function does not return a value. 


By calling this function, the window procedure that receives the message allows 
the task that called SendMessage to continue to run as though the task that re- 
ceived the message had returned control. The task that calls ReplyMessage also 
continues to run. 


Usuaily, a iask illai calis Send Message iv seud a message io anvilier iask will nui 
continue running until the window procedure that Windows calls to receive the 
message returns. However, if a task that is called to receive a message must per- 
form some type of operation that might yield control (such as calling the Message- 
Box or DialogBox function), Windows could be deadlocked, as when the sending 
task must run and process messages but cannot because it is waiting for 


See Also 


‘ResetDC 


#include <print.h> 


HDC ResetDC(hdc, Ipdm) 
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SendMessage to return. An application can avoid this problem if the task receiv- 
ing the message calls ReplyMessage before performing any open that could 
cause the task to yield. 


The ReplyMessage function has no effect if the message was not sent through the 
Send Message function or if the message was sent by the same task. 


DialogBox, MessageBox, SendMessage 


HDC hdc; | /* handle of device context */ 
const DEVMODE FAR®* lpdm; /* address of DEVMODE structure Sef 


Parameters 


hdc 


_ The ResetDC function updates the given device context, based on the information 


in the Same DEVMODE structure. 


Identifies the device context to be updated. 
[pdm | | 
Points to a DEVMODE structure containing information about the new device 
context. The DEVMODE structure has the following form: 


#Finclude <print.h> 


typedef struct tagDEVMODE { /* dm */ 
char dmDeviceName[CCHDEVICENAME]; 
UINT dmSpecVersion; 
UINT dmDriverVersion; 
UINT dmSize; 
UINT dmDriverExtra; 
DWORD dmFields; 
int  dmOrientation; 
int dmPaperSize;. 
int dmPaperLength; 
int dmPaperWidth; 
int dmScale; 
int  dmCopies; | 
int dmDefaultSource; 
int dmPrintQuality; 


_ 192 ResizePalette 


int dmColor; 
int dmDuplex; | 
int dmYResolution; 
int dmTTOption; 
} DEVMODE; , 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value — The return value is the handle of the original device context if the function is 
successful. Otherwise, it is NULL. 


Comments An application will typically use the ResetDC function when a window receives a 
WM_DEVMODECHANGE message. ResetDC can also be used to change the 
paper orientation or paper bins while printing a document. 


The ResetDC function cannot be used to change the driver name, device name or 
the output port. When the user changes the port connection or device name, the ap- 
plication must delete the original device context and create a new device context © 
with the new information. 


Before calling ResetDC, the application must ensure that all objects (other than 
stock objects) that had been selected into the device context have been selected out. 


— See Also DeviceCapabilities, Escape, ExtDeviceMode 


ResizePalette _ 


BOOL ResizePalette(hpal, cEntries) 
HPALETTE hpal; /* handle of palette i 
UINT cEntries; /* number of palette entries after resizing ee 


The ResizePalette function changes the size of the given logical palette. 


Parameters hpal 
Identifies the palette to be changed. 


cEntries 7 
Specifies the number of entries in the palette after it has been resized. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments If an application calls the ResizePalette function to reduce the size of the palette, 
the entries remaining in the resized palette are unchanged. If the application calls 


RestoreDC 
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ResizePalette to enlarge the palette, the additional palette entries are set to black 
(the red, green, and blue values are all zene) and the flags for all additional entries 
are set to zero. 


BOOL RestoreDC(hdc, nSavedDC) 


HDC hdc; 


int nSavedDC; 


Parameters 


Return Value 


Comments 


Example 


/* handle of device context **/ 
/* integer identifying device context to restore mh 


The RestoreDC function restores the given device context to a previous state. 
The device context is restored by popping state information off a stack created by 
earlier calls to the SaveDC function. 


hdc 
Identifies the device context. 


nSavedDC 
Specifies the device context to be restored. This parameter can be a value re- 
turned by a previous SaveDC function. If the parancle is —1, the most recently 
saved device context is restored. | 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The stack can contain the state information for several instances of the device con- 
text. If the context specified by the nSavedDC parameter is not at the top of the 
stack, RestoreDC deletes all state information between the instance specified by 
nSavedDC and the top of the stack. 


The following example uses the GetMapMode function to retrieve the mapping 
mode for the current device context, uses the SaveDC function to save the state of 
the device context, changes the mapping mode, restores the previous state of the 
device context by using the RestoreDC function, and retrieves the mapping mode 
again. The final mapping mode is the same as the mapping mode prior t to the call 
to the SaveDC function. 


HDC hdcLocal; 
int MapMode; 


~ char *aModes[] = {"ZERO", "MM_TEXT", "MM_LOMETRIC", “MM_HIMETRIC", 


“"MM_LOENGLISH", “MM_HIENGLISH", "“MM_TWIPS", 
"MM_ISOTROPIC", "MM_ANISOTROPIC™ }; 


hdcLocal = GetDC(hwnd); 


MapMode = GetMapMode(hdcLocal); 


794 RoundRect 

TextOut(hdc, 100, 100, (LPSTR) aModes[MapModel, 
lTstrlen(aModes[MapMode])); 

SaveDC(hdcLocal); 

SetMapMode(hdcLocal, MM_LOENGLISH); 

MapMode = GetMapMode(hdcLocal); 

TextOut(hdc, 100, 120, (LPSTR) aModes[MapMode], 
lstrlen(aModes[MapMode])); 

RestoreDC(hdcLocal, -1); 

MapMode = GetMapMode(hdcLocal); 

TextOut(hdc, 100, 140, (LPSTR) aModes[MapMode], 
Tstrlen(aModes[MapMode])); 


ReleaseDC(hwnd, hdcLocal); 


See Also SaveDC 


RoundRect —— _ ex] 


BOOL RoundRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nEllipse Width, nEllipseHeight) 


HDC hdc; /* handle of device context si | 
int nLeftRect; /* x-coordinate upper-left corner ‘a | 
int nTopRect; /* y-coordinate upper-left corner i | 
int nRightRect; /* x-coordinate lower-right corner */ 
int nBottomRect; /* y-coordinate lower-right corner | 
int nEllipse Width; /* width of ellipse for rounded corners mi 


int nEllipseHeight; /* height of ellipse for rounded corners si 


The RoundRect function draws a rectangle with rounded corners, using the cur- 
rent pen. The interior of the rectangle is filled by using the current brush. 


Parameters hdc 
Identifies the device context. 
nLeftRect o 28 
Specifies the logical x-coordinate of the upper-left corner of the rectangle. 
nTopRect © | 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


nRightRect 
Specifies the logical x-coordinate of the lower-right corner of the rectangle. 
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nBottomRect 
Specifies the logical y-coordinate of the lower-right corner of the rectangle. 
nEllipseWidth 
Specifies the width, in logical units, of the ellipse used to draw the rounded 
corners. 
nEllipseHeight 


Specifies the height, in logical units, of the ellipse used to draw the rounded 
comers. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments ___ The figure this function draws extends up to but does not include the right and 
bottom coordinates. This means that the height of the figure is nBottomRect — 
nTopRect and the width of the figure is nRightRect — nLeftRect. 


Both the width and the height of a rectangle must be greater than 2 units and less 
than 32,767 units. 


Example | The following example uses a RECT structure to store the coordinates used by the 
| RoundRect function: 


HDC hdc; 


RECT rc = { 10, 10, 180, 140 }; 
int iEllipseWidth, iEllipseHeight; 


iEllipseWidth = 20; 
i1EllipseHeight = 40; 


RoundRect(hdc, rc.left, rce.top, rc.right, rc.bottom, 
iEllipseWidth, iEllipseHeight); 


See Also Rectangle | 


SaveDC af a x] 


int SaveDC(hdc) 
HDC hdc; [* handle of device context */ 


The SaveDC function saves the current state of the given device context by. copy- 
ing state information (such as clipping region, selected objects, and mapping 
mode) to a context stack. The saved device context can later be restored by using 
the RestoreDC function. 


796 SaveDC 


Parameters 


Return Value 


Comments 


Example 


See Also 


hdc | 
Identifies the device context to be saved. 


The return value is an integer identifying the saved device context if the function 
is successful. This integer can be used to restore the device context by calling the 
RestoreDC function. The return value is zero if an error occurs. 


The SaveDC function can be used any number of times to save any number of 
device-context states. 


The following example uses the GetMapMode function to retrieve the mapping 
mode for the current device context, uses the SaveDC function to save the state of 
the device context, changes the mapping mode, restores the previous state of the 
device context by using the RestoreDC function, and retrieves the mapping mode 
again. The final mapping mode is the same as the mapping mode prior to the call 
to the SaveDC function. 


HDC hdcLocal; 

int MapMode; 

char *aModes[] = {"ZERO", "MM_TEXT", "MM_LOMETRIC", "MM_HIMETRIC", 
"MM_LOENGLISH", “MM_HIENGLISH", "MM_TWIPS", . 
"MM_ISOTROPIC", "MM_ANISOTROPIC" }; 


hdcLocal = GetDC(hwnd); 

MapMode = GetMapMode(hdcLocal ); 

TextOut(hdc, 100, 100, (LPSTR) aModes[MapMode], 
lstrlen(aModes[MapMode])); 


SaveDC(hdcLocal ); 

SetMapMode(hdcLocal, MM_LOENGLISH) ; 

MapMode = GetMapMode(hdcLocal ); 

TextOut(hdc, 100, 120, (LPSTR) aModes[MapMode], 
lstrlen(aModes[MapMode])); 

RestoreDC(hdcLocal, -1); 

MapMode = GetMapMode(hdcLocal ); 

TextOut(hdc, 100, 140, (LPSTR) aModes[MapMode], 
lstrlen(aModes[MapMode])); 


ReleaseDC(hwnd, hdcLocal); 


RestoreDC 
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scaleViewportExt : [ 2.x | 


DWORD ScaleViewportExt(hdc, nxNum, nXDenom, nYNum, nYDenom) 


HDC hdc; 

int nXNum; 
int nXDenom; 
int nYNum; — 
int nYDenom; 


Parameters . 


Return Value 


Comments 


Example 


/* handle of device context i | 
/* amount by which current x-extent is multiplied */ 
/* amount by which current x-extent is divided */ 
/* amount by which current y-extent is multiplied . | 
/* amount by which current y-extent is divided a 


The Scale ViewportExt function modifies the viewport extents relative to the cur- 
rent values. 


hdc 
Identifies the device context. 


nXNum 
Specifies the amount by which to multiply the current x-extent. 


nXDenom 
Specifies the amount by which to divide the result of multiplying the current 
x-extent by the value of the nXNum parameter. 


nYNum 
Specifies the amount by which to multiply the current y-extent. 


nYDenom 
Specifies the amount by which to divide the result of multiplying the current | 
y-extent by the value of the nYNum parameter. 


The low-order word of the return value contains the x-extent, in device units, of 
the previous viewport if the function is successful; the high-order word contains 
the y-extent. 


The new viewport extents are calculated by multiplying the current extents by the 
given numerator and then pividing by the given denominator, as shown in the fol- 


lowing formulas: 


nXNewVE 
nYNewVE 


(nXO1dVE * nXNum) / nXDenom 
(nYOIdVE * nYNum) / nYDenom 


The following example draws a rectangle that is 4 logical units high and 4 logical 
units wide. It then calls the ScaleViewportExt function and draws a rectangle that 
is 8 units by 8 units. Because of the viewport scaling, the second pecaneed is the 
Same size as the first. 
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HDC hdc; 

~ RECT re; 
GetClientRect(hwnd, &rc); 
hdc = GetDC(hwnd) ; 
SetMapMode(hdc, MM_ANISOTROPIC); 
SetWindowExt(hdc, 10, 10); 
SetViewportExt(hdc, rc.right, rc.bottom); 
Rectangle(hdc, 3, 3, 7, 7); 


ScaleViewportExt(hdc, 1, 2, 1, 2); 
Rectangle(hdc, 6, 6, 14, 14); 


ReleaseDC(hwnd, hdc); 


See Also Get ViewportExt 


ocaleViewportExtEx aa 


BOOL ScaleViewportExtEx(hdc, nXnum, nXdenom, nYnum, nYdenom, IpSize) 


HDC hdc; /* handle of device context */ 
int nXnum; /* amount by which current x-extent is multiplied | 
int nXdenom; /* amount by which current x-extent is divided | 
int nYnum; /* amount by which current y-extent is multiplied sa | 
int nYdenom; /* amount by which current y-extent is divided if 
SIZE FAR* [pSize; /* address of SIZE structure i 


The Scale ViewportExtEx function modifies the viewport extents relative to the 
current values. The formulas are written as follows: 


(xO1dVE * Xnum) / Xdenom 
(yOldVE * Ynum) / Ydenom 


XNewVE 
yNewVE 


The new extent is calculated by multiplying the current extents by the given 
numerator and then dividing by the given denominator. 


Parameters hde 
- Identifies the device context. 


nXnum | 
Specifies the amount by which to multiply the current x-extent. 


nXdenom | 
Specifies the amount by which to divide the current x-extent. 


Return Value 
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nYnum | 
Specifies the amount by which to multiply the current y-extent. 


nYdenom | 
Specifies the amount by which to divide the current y-extent. 


lpSize 
Points to a SIZE structure. The previous viewport extents, in device units, are 
placed in this structure. If JpSize is NULL, nothing is returned. | 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


ocaleWindowExt | 


DWORD ScaleWindowExt(hdc, nXNum, nXDenom, nYNum, nYDenom) 


HDC hdc; 

int nXNum; 
int nXDenom; 
int nYNum; 
int nYDenom; 


Parameters | 


Return Value 


/* handle of device context sa 
/* amount by which current x-extent is multiplied sa | 
/* amount by which current x-extent is divided ) 
/* amount by which current y-extent is multiplied */ 
/* amount by which current y-extent is divided a | 


The ScaleWindowExt function modifies the window extents relative to the cur- 
rent values. 


hdc —_ 
Identifies the device context. 


nXNum > 
Specifies the amount by which to multiply the current x-extent. 


nXDenom 
Specifies the amount by which to divide the result of multiplying the current 
x-extent by the value of the nXNum parameter. 


nYNum 
Specifies the amount by which to multiply the current y -extent. 


nYDenom 
Specifies the amount by which to divide the result of multiplying the current 
y-extent by the value of the nYNum parameter. 


The low-order word of the return value contains the x-extent, in logical units, of 
the previous window, if the function is successful; the high-order word contains 
the y-extent. 


800 _- ScaleWindowExtEx 


Comments 


Example 


See Also 


The new window extents are calculated by multiplying the current extents by the 
given numerator and then dividing by the given denominator, as shown in the fol- 
lowing formulas: 


nXNewWE = (nXO1dWE * nXNum) / nXDenom 
nYNewWE = (nYOIdWE * nYNum) / nYDenom 


The following example draws a rectangle that is 4 logical units high and 4 logical 
units wide. It then calls the ScaleWindowExt function and draws a rectangle that 
is 8 units by 8 units. Because of the window scaling, the second rectangle is the 
same size as the first. 


HDC hdc; 
RECT rc; 


GetClientRect(hwnd, &rc); 

hdc = GetDC(hwnd); 

SetMapMode(hdc, MM_ANISOTROPIC); 
SetWindowExt(hdc, 10, 10); 
SetViewportExt(hdc, rc.right, rc.bottom); 
Rectangle(hdc, 3, 3, 7, 7); 


ScaleWindowExt(hdc, 2, 1, 2, 1); 
Rectangle(hdc, 6, 6, 14, 14); 


ReleaseDC( hwnd, hdc); 


Get WindowExt 


ocaleWindowExtEx | :EXE 


_ BOOL ScaleWindowExtEx(hdc, nXnum, nXdenom, nYnum, nYdenom, IpSize) 


HDC hdc; 

int nXnum; 

int nXdenom; 

int nYnum; 

int nYdenom; 
STZE FAR®* IpSize: 


/* handle of device context */ 
/* amount by which current x-extent is multiplied — */ 
/* amount by which current x-extent is divided ca 
/* amount by which current y-extent is multiplied */ 
/* amount by which current y-extent is divided i 
/* address of STZE structure 7 


The ScaleWindowExtEx function modifies the window extents relative to the cur- 
rent values. The formulas are written as follows: | 


xNewWE 


= (xOIdWE * Xnum) / Xdenom 
yNewWE = ( 


yOlIdWE * Ynum) / Ydenom 
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_ The new extent is calculated by multiplying the current extents by the given 
numerator and then dividing by the given denominator. 


Parameters hdc 
Identifies the device context. 


nXnum 
Specifies the amount by which to multiply the current x-extent. 


nXdenom | | 
Specifies the amount by which to divide the current x-extent. 


nYnum | 
Specifies the amount by which to multiply the current y-extent. 


nYdenom | 
Specifies the amount by which to divide the current y-extent. 


lpSize 
Points to a SIZE structure. The previous window extents, in logical units, are 
placed in this structure. If IpSize is NULL, nothing is returned. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


ScreenToClient 7 ee. Tat 


void ScreenToClient(hwnd, lppt) 
HWND hwnd; /* window handle for source coordinates sf 
POINT FAR* [ppt; /* address of structure with coordinates **/ 


The ScreenToClient function converts the screen ‘coordinates of a given point on 
the screen to client coordinates. : 


Parameters hwnd 

| Identifies the window whose client area is to be used for the conversion. 

lppt | 
Points to a POINT structure that contains the screen coordinates to be con- 
verted. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; | 
int y; 

} POINT; 


For a full description of this structure, see the M icrosofi | Windows oe 
mer’s Reference, Volume 3. 


802 ScrollDC 


Return Value 


Comments 


Example 


This function does not return a value. 


The ScreenToClient function replaces the screen coordinates in the POINT struc- 
ture with client coordinates. The new coordinates are relative to the upper-left 
corner of the given window’s client area. 


The following example uses the GetWindowRect function to retrieve the screen 
coordinates for a specified window, calls the ScreenToClient function to convert 
the upper-left and lower-right corners of the window rectangle to client coordi- 
nates, and then reports the results in a message box: , 


RECT rc; /* window's screen coordinates * / 
POINT ptUpperLeft; /* client coordinate of upper left */ 
POINT ptLowerRight; /* client coordinate of lower right */ 
char szText[128]; /* char buffer for wsprintf * / 


GetWindowRect(hwnd, &rc); 


ptUpperLeft.x = prc.left; 
ptUpperLeft.y = rc.top; 
ptLowerRight.x = rc.right; 
ptLowerRight.y = rc.bottom; 


ScreenToClient(hwnd, &ptUpperLeft ); 
ScreenToClient(hwnd, &ptLowerRight); 


wsprintf(szText, 
"S: (4d,%4d)-(4d,%4d) --> C: (4d,%d)-(%4d,4d)", 
rc.left, rc.top, rc.right, rc.bottom, . 
ptUpperLeft.x, ptUpperLeft.y, ptLowerRight.x, ptLowerRight.y); 


MessageBox(hwnd, szTlext, "ScreenToClient", MB_OK); 


See Also 


ScrollDC 


ClientToScreen, MapWindowPoints 


BOOL SerollDC( hide, dx, dy, [prcScroll, IprceClip, hrgnUpdate, iprcUpdate) 


HDC hdc: /* handle of device context : **/ 
int dx; /* horizontal scroll units **/ 
int dy; /* vertical scroll units , sa | 
const RECT FAR® [prcScroll; /* address of scrolling rectangle cas y Sh 
const RECT FAR® [prcClip; /* address of clipping rectangle */ 
HRGN hrgnUpdate; /* handle of scrolling region : sa) 


RECT FAR* [prcUpdate;_ —~—s/* address of structure for update rect. ook. 


Parameters 


Return Value 


Comments 


ScrollDC 803 


The ScrolIDC function scrolls a rectangle of bits horizontally and vertically. 


hdc 


Identifies the device context that contains the bits to be scrolled. 


dx 
Specifies the number of horizontal scroll units. 


dy 
Specifies the number of vertical scroll units. 


lprcScroll — 
Points to the RECT structure that contains the coordinates of the scrolling — 
rectangle. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s en Volume 3. 


lprcClip — 
Points to the RECT structure that contains the coordinates of the clipping 
rectangle. When this rectangle is smaller than the original one pointed to by the 
IprcScroll parameter, sre occurs only in the smaller rectangle. 


hrgnUpdate 
Identifies the region uncovered by the scrolling process. The ScrollDC function 
defines this region; it is not necessarily a rectangle. 


[prcUpdate 
Points to the RECT structure that receives the coordinates of the rectangle that 
bounds the scrolling update region. This is the largest rectangular area that re- 
quires repainting. The values in the structure when the function returns arein 
client coordinates, regardless of the mapping mode for the given device context. 


_The return value is nonzero if the function is successful. Otherwise, it is zero. 


If the IprcUpdate parameter is NULL, Windows does not compute the update 
rectangle. If both the hrguUpdate and lprcUpdate parameters are NULL, Win- 
dows does not compute the update region. If hrgn Update is not NULL, Windows 
assumes that it contains a valid handle of the region uncovered by the OTe. 
process (defined by the ScrolIDC function). " 


~ When the ScrollDC function returns, the values in the structure pointed to by the 


[prc Update parameter are in client coordinates. This allows applications to use the | 


update region in a call to the InvalidateRgn function, if required. 


804 ScrollWindow 


An application should use the ScrollWindow function when it is necessary to 
scroll the entire client area of a window; otherwise, it should use ScrollDC. 


See Also InvalidateRgn, ScrollWindow, ScrollWindowEx 


ScrollWindow 


void ScrollWindow(hwnd, dx, dy, lprcScroll, lprcClip) 


HWND hwnd; /* handle of window to scroll * / 
int dx; /* amount of horizontal scrolling */ 
int dy; /* amount of vertical scrolling 7] 
const RECT FAR® /prcScroll; /* address of structure with scroll rect. | 
const RECT FAR® /prcClip; /* address of structure with clip rect. ** / 
The ScrollWindow function scrolls the contents of a window’s client area. 
Parameters hwnd 


dx 


dy 


Identifies the window to be scrolled. 


Specifies the amount, in device units, of horizontal scrolling. This parameter | 
must be a negative value to scroll to the left. 


Specifies the amount, in device units, of vertical scrolling. This parameter must 
be a negative value to scroll up. 


lprcScroll 
- Points to a RECT structure that specifies the portion of the client area to be 


scrolled. If this parameter is NULL, the entire client area is scrolled. The caret 
is repositioned if the cursor rectangle intersects the scroll rectangle. 


The RECT structure has the following form: 


typedef struct tagRECT { /* reo */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’ s Reference, Volume 3. 


lprcClip : 


Points to a RECT structure that specifies the clipping rectangle to scroll. This 
structure takes precedence over the rectangle pointed to by /prcScroll. Only bits 


- Return Value 


Comments 


ScrollWindowEx 805 


inside this rectangle are scrolled. Bits outside this rectangle are not scrolled, 
even if they are in the /prcScroll rectangle. If this parameter is NULL, no clip- 
ping is performed on the scroll rectangle. | 


This function does not return a value. 


If the caret is in the window being scrolled, ScrollWindow automatically hides 
the caret to prevent it from being erased, then restores the caret after the scroll is 
finished. The caret position is adjusted accordingly. 


The area uncovered by the Scroll Window function is not repainted, but it is com- 
bined into the window’s update region. The application will eventually receive a 
WM_PAINT message notifying it that the region needs repainting. To repaint the 
uncovered area at the same time the scrolling is done, call the UpdateWindow 
function immediately after calling ScrollWindow. 


If the /prcScroll parameter is NULL, the positions of any child windows in the 
window are offset by the amount specified by the dx and dy parameters, and any 
invalid (unpainted) areas in the window are also offset. ScrollWindow is faster 
when IprcScrollis NULL. 


If the /prcScroll parameter is not iti the positions of child windows are not 
changed and invalid areas in the window are not offset. To prevent updating prob- 
lems when /prcScroll is not NULL, call the UpdateWindow function to repaint 


_ the window before calling Scroll Window. 


See Also 


ScrollWindowEx 


ScrollIDC, Scroll WindowEx, UpdateWindow | 


int SerollWindowEx(hwnd, dx, dy, lprcScroll, IpreClip, hrgnUpdate, lprcUpdate, pScroll 


HWND hwnd; /* handle of window to scroll 
intdx; /* amount of horizontal scrolling | . 
int dy; /* amount of vertical scrolling | 
const RECT FAR®* [prcScroll; /* address of structure with scroll rect. +} 
const RECT FAR®* /prcClip; /* address of structure with clip rect. i 
HRGN hregnUpdate; /* handle of update region | if | 
RECT FAR? [prcUpdate; /* address of structure for update rect. ) 
/* scrolling flags 7 nee 


UINT fuScroll; 


The ScrollWindowEx function scrolls the contents of a window’s client area. 
This function is similar to the ScrollWindow function, with some additional 
features. 


806 ScrollWindowEx 


Parameters hwnd 


Identifies the window to be scrolled. 


dx 


dy 


Specifies the amount, in device units, of horizontal scrolling. This parameter 
must be a negative value to scroll to the left. 


Specifies the amount, in device units, of vertical scrolling. This parameter must 
be a negative value to scroll up. 


lprcScroll . 


Points to a RECT structure that specifies the portion of the client area to be 
scrolled. If this parameter is NULL, the entire client area is scrolled. The 
RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


IprcClip 


Points toa RECT structure that specifies the clipping rectangle to scroll. This 

structure takes precedence over the rectangle pointed to by the /prcScroll pa- _ 
rameter. Only bits inside this rectangle are scrolled. Bits outside this rectangle 

are not affected even if they are in the /prcScroll rectangle. If this parameter is 

NULL, no clipping is performed on the scroll erate 


hren Update 


Identifies the region that is modified to hold the region invalidated by scrolling. - 
This parameter may be NULL. 


lprcUpdate 


Points to a RECT structure that will receive the boundaries of the rectangle in- 
validated by scrolling. This parameter may be NULL. 


fuScroll 


Specifies flags that control scrolling. This epaaner can be one of the follow- 
ing values: 


Return Value 


Comments 


See Also 
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Value Meaning 


SW_ERASE When specified with SW_INVALIDATE, erases 
the newly invalidated region by sendinga 
WM_ERASEBKGND message to the window. 

SW_INVALIDATE Invalidates the region identified by the hrgnUpdate 
parameter after scrolling. 

SW_SCROLLCHILDREN Scrolls all child windows that intersect the rectangle 
pointed to by I[prcScroll by the number of pixels 
specified in the dx and dy parameters. Windows 
sends a WM_MOVE message to all child windows 
that intersect [prcScroll, even if they do not move. 
The caret is repositioned when a child window is 
scrolled and the cursor rectangle intersects the scroll — 
rectangle. 


The return value is SIMPLEREGION Gasansala: invalidated region), 
COMPLEXREGION (nonrectangular invalidated region; overlapping eegaues. 
or NULLREGION (no invalidated region), if the function is successful. Other- 
wise, the return value is ERROR. - 


If SW_INVALIDATE and SW_ERASE are not specified, ScrollWindowEx does 
not invalidate the area that is scrolled away from. If either of these flags 1s set, | 
ScrollWindowEx invalidates this area. The area is not updated until the applica-_ 
tion calls the UpdateWindow function, calls the RedrawWindow function spect 


- fying RDW_UPDATENOW or RDW_ERASENOW), or retrieves the 


WM_PAINT message from the application queue. 


If the window has the WS_CLIPCHILDREN style, the returned areas specified by 
hrgnUpdate and lprcUpdate represent the total area of the scrolled window that 
must be updated, including any areas in child windows that need qupdating. — 


If the SW_SCROLLCHILDREN flag is specified, Windows will not properly up- 
date the screen if part of a child window is scrolled. The part of the scrolled child 
window that lies outside the source rectangle will not be erased and will not be 
redrawn properly in its new destination. Use the DeferWindowPos function to 


move child windows that do not lie completely within the /prcScroll rectangle. 


All input and output coordinates (for IprcScroll, lprcClip, lprcUpdate, and 
hrgnUpdate) are assumed to be in client coordinates, regardless of whether the - 
window has the CS_OWNDC or CS_CLASSDC class style. Use the LPtoDP and 


DPtoLP functions to convert to and from logical coordinates, if necessary. 


RedrawWindow, ScrollDC, ScrollWindow, UpdateWindow 


808 SelectClipRgn 


SelectClipRgn rex 


int SelectClipRgn(hdc, hrgn) 
HDC hdc; /* handle of device context id 
HRGN hrgn;_ _—/* handle of region i | 


The SelectClipRgn function selects the given region as the current clipping region 
for the given device context. | | 


Parameters hdc 
Identifies the device context. 


hrgn 
Identifies the region to be selected. If this value is NULL, the entire client area 
is selected and output is still clipped to the window. 


Return Value The return value is SSMPLEREGION (region has no overlapping borders), 
COMPLEXREGION (region has overlapping borders), or NULLREGION (region 
is empty), if the function is successful. Otherwise, the return value is ERROR. 


Comments The SelectClipRgn function selects only a copy of the specified region. Because 
_ SelectClipRgn uses only a copy, the region can be selected for any number of 
other device contexts or it can be deleted. 


The coordinates for the specified region should be specified in device units. 


Some printer devices support text output at a higher resolution than graphics out- 
put in order to retain the precision needed to express text metrics. These devices re- 
port device units at the higher resolution—that 1s, text units. These devices then 
scale coordinates for graphics so that several reported device units map to only 
one graphics unit. Applications should always call the SelectClipRgn function 
using the text unit. Applications that must take the scaling of graphics objects in 
the graphics device interface (GDI) can use the, GETSCALINGFACTOR printer 
escape to determine the scaling factor. This scaling factor affects clipping. If a re- 
gion is used to clip graphics, GDI divides the coordinates by the scaling factor. (If 
the region is used to clip text, however, GDI makes no scaling adjustment.) A scal- 
- ing factor of 1 causes the coordinates to be divided by 2; a scaling factor of 2 
causes the coordinates to be divided by 4; and so on. 


Example ___ The following example uses the GetClipBox function to determine the size of the 
Cuirent Clipping region ana the GetLextExtent fiction to determine the widib of 
— aline of text. If the text will not fit in the clipping region, the SelectClipRgn is 
used to make the region wide enough for the text. The output is clipped to the win- 
dow regardless of the size of the region specified in the second parameter of 
SelectClipRegion. | 


SelectObject 809 


HRGN hrgnClip; 

RECT rcClip; 

LPSTR IpszTest = "Test of clipping region."; 
DWORD dwStringLen; 

WORD wExtent; 


GetClipBox(hdc, &rcClip); | 
dwStringLen = GetTextExtent(hdc, IpszTest, Istrlen(lpszTest)); 
wExtent = LOWORD(dwStringLen) ; 
if (rcClip.right < 5@ + wExtent) { 
hrgnClip = CreateRectRgn(5@, 50, 50 + wExtent, 80); 
SelectClipRgn(hdc, ee 
} 


TextOut(hdc, 50, 60, IpszTest, Istrlen(lpszTest)); 


DeleteObject(hrgnClip); 


See Also Get ClipBox, GetTextExtent 


SelectObject a me oe ae 


| HGDIOBJ SelectObject(hdc, hediobj) | | eo 
HDC hdc; _ /* handle of device context ‘a 
HGDIOBJ hgdiobj; | Bye handle of object fasta = 


The SelectObject function selects an object into the given device context. The 
new object replaces the previous object of the same type. 


Parameters hdc 
| Identifies the device context. 
hgdiobj 
Identifies the object to be selected. The object can be one of the following and > 
must have been created by USInE O one of the listed functions: 


Object Functions | 
Bitmap —|- CreateBitmap, CreateBitinaplndirect, gee ee 
| CreateDIBitmap | 
Brush —_‘ CreateBrushIndirect, CreateDIBPatternBrush, 
_ CreateHatchBrush, CreatePatternBrush, CreateSolidBrush 
Font - CreateFont, CreateFontIndirect 


Pen CreatePen, CreatePenIndirect 


810 SelectObject 


Return Value 


Comments 


Object © _—_— Functions 


Region CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, 
CreateRoundRectRgn, CreateRectRgn, CreateRectRgnIndirect 


The return value is the handle of the object being replaced, if the function is 
- successful. Otherwise, itis NULL. 


If the hgdiobj parameter identifies a region, this function performs the same task 
as the SelectClipRgn function and the return value is SIMPLEREGION (region 
has no overlapping borders), COMPLEXREGION (region has overlapping 
borders), or NULLREGION (region is empty). If an error occurs, the return value 
is ERROR and the previously selected object of the specified type remains 
selected in the device context. 


When an application uses the SelectObject function to select a font, pen, or brush, 
the system allocates space for that object in its data segment. Because data- 
segment space is limited, an application should use the DeleteObject function to 
remove each drawing object that it no longer requires. Before removing the object, 
the application should select it out of the device context. To do this, the applica- 
tion can select a different object of the same type back into the device context; 


_ typically, this different object is the original object for the device context. 


Example 


When the hdc parameter identifies a metafile device context, the SelectObject 
function does not return the handle of the previously selected object. When the 
device context is a metafile, calling SelectObject with the hgdiobj parameter set 
to a value returned by a previous call to SelectObject can cause unpredictable re- 
sults. Because metafiles perform their own object cleanup, an application need not 
reselect default objects when recording a metafile. 


Memory device contexts are the only device contexts into which an application 
can select a bitmap. A bitmap can be selected into only one memory device con- 
text at a time. The format of the bitmap must either be monochrome or be compat- 
ible with the given device; if it is not, Se returns an error. 


The following exaniple creates a pen, uses the SelectObject function to select it 
into a device context, uses the pen to draw a rectangle, selects the previous pen 
back into the device context, and uses the DeleteObject function to remove the 


_ pen that was just created: 


HPEN hpen, hpenOld; 


hpen = CreatePen(PS_SOLID, 6, RGB(@, @, 255)); 
hpenOld = SelectObject(hdc, hpen); 


Rectangle(hdc, 10,-10, 100, 100); 


See Also 


SelectPalette 811 


SelectObject(hdc, hpenOld); 
DeleteObject(hpen); 


DeleteObject, SelectClipRgn, SelectPalette 


SelectPalette- 


HPALETTE SelectPalette(hdc, hpal, fPalBack) 


HDC hdc; 


HPALETTE hpai; 


_ BOOL fPalBack; 


Parameters 


Return Value 


— Comments 


Example 


/* handle of device context a 
/* handle of palette +} 
/* flag for forcing palette to background eh 


The SelectPalette function selects the specified logical palette into the given 
device context. The selected palette replaces the previous palette for that device 
context. 


hdc 
Identifies the device context. 
hpal 
Identifies the logical palette to be selected. 


fPalBack 
Specifies whether the logical palette is always to be a background palette. If 
this parameter is nonzero, the selected palette is always a background palette. If 
this parameter is zero and the device context is attached to a window, the logi- 
cal palette is a foreground palette when the window has the input focus. (The 
device context is attached to a window if it was obtained by using the GetDC 
function or if the window-class style is CS_OOWNDC.) 


The return value is the handle of the previous logical palette for the given device 
context, if the function is successful. Otherwise, it is NULL. 


An application can select a logical palette into more than one device context. 
However, changes to a logical palette will affect all device contexts for which it is 
selected. If an application selects a palette into more than one device context, the 


_ device contexts must all belong to the same physical device. 


The following example calls the SelectPalette function to select a logical palette 
into a device context and then calls the RealizePalette function to change the 
Peru size: 


812 SendDigitemMessage 


See Also 


SendDigitemMessage 


HPALETTE hpal, hPalPrevious; 

hdc = GetDC(hwnd); 

hPalPrevious = SelectPalette(hdc, hpal, FALSE); 
if (RealizePalette(hdc) == NULL) 


MessageBox(hwnd, "Can't realize palette", "Error", MB_OK); 


ReleaseDC(hwnd, hdc); 


CreatePalette, GetDC, RealizePalette 


LRESULT SendDlgltemMessage(hwnaDig, idDigItem, uMsg, wParam, lParam) 
*/ 


HWND hwndDig; /* handle of dialog box 
int idDigItem; /* identifier of dialog box item = 
UINT uMsg;3 /* message — a | 
WPARAM wParam; /* first message parameter a) 
LPARAM /Param; /* second message parameter a 

The SendDlgItemMessage function sends a message to a control in a dialog box. 
Parameters hwndaDlg 

Identifies the dialog box that contains the control. 
idDigItem 


Return Value 


Comments 


Specifies the identifier of the dialog item that will receive the message. 


uMsg 
Specifies the message to be sent. 


wParam | 
Specifies 16 bits of additional message-dependent information. 


[Param 
Specifies 32 bits of additional message-dependent information. 


The return value specifies the result of the message processing and depends on the 
message sent. 


The SendDigItemMessage function does not return until the message has been 


processed. 


SendDriverMessage 813 


Using SendDlgItemMessage is identical to retrieving a handle of the given con- 
trol and calling the SendMessage function. 


See Also — PostMessage, SendMessage 


SendDriverMessage - Ba 


LRESULT SendDriverMessage(hdrvr, msg, [Param], [Param2) 


HDRVR hdrvr; | /* handle of installable driver **/ 
UINT msg; /* message **/ 
LPARAM [Param]; /* first message parameter ‘| 


LPARAM /Param2; /* second message parameter | 


The SendDriverMessage function sends the specified message to the given install 
able driver. 


Parameters — hdrvr 
Identifies a installable driver. 


msg 
Specifies the message e that the driver must process. The following messages _ 
should never be sent by an application directly to the driver; they are sent one 
by the system: 


DRV_CLOSE | 
DRV_DISABLE 
DRV_ENABLE 
DRV_EXITAPPLICATION 
DRV _EXITSESSION 
DRV_FREE 

DRV_LOAD 

DRV_OPEN 


lParam! 
Specifies 32 bits of additional meestee eepencent information. 


l[Param2 
Specifies 32 bits of additional message-dependent information. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also DefDriverProc 


814 SendMessage 


sendMessage 


LRESULT SendMessage(hwnd, uMsg, wParam, l|Param) 


HWND hwnd; 
UINT uMsg; 


WPARAM wParam; | 


LPARAM /Param; 


/* handle of destination window */ 
/* message to send =] 
/* first message parameter | 
/* second message parameter */ 


The SendMessage function sends the specified message to the given window or 
windows. The function calls the window procedure for the window and does not 


return until that window procedure has processed the message. This is in contrast 


Parameters 


Return Value 


Comments 


_ Example 


See Also 


to the PostMessage function, which places (posts) the message in the window’s 
message queue and returns immediately. 


hwnd | 
Identifies the window to which the message will be sent. If this parameter is 
HWND_BROADCAST, the message will be sent to all top-level windows, 
including disabled or invisible unowned windows. 


uMsg ) 
Specifies the message to be sent. 


wParam 
Specifies 16 bits of additional message-dependent information. 


[Param 
Specifies 32 bits of additional message-dependent information. 


_ The return value specifies the result of the message processing and depends on the 


message sent. | 


If the message is being sent to another application and the wParam or [Param pa- 
rameter is used to pass a handle or pointer to global memory, the memory should 
be allocated by the GlobalAlloc function using the GMEM_SHARE flag. 


The following example calls the SendMessage function to send an EM_SETSEL 
message to a multiline edit control, telling it to select all the text. It then calls 
Send Message to send a WM_COPY message to copy the selected text to the clip- 
board. | 


SendMessage(hwndMle, EM_SETSEL, @, MAKELONG(@, -1)); 
SendMessage(hwndMle, WM COPY. @. @L): | 


InSendMessage, PostMessage, SendDlgItemMessage 


SetActiveWindow 815 


SetAbortProc EXE 


int SetAbortProc(hdc, abrtprc) e 
HDChdc; /* handle of device context a 
ABORTPROC abrtprc;__‘/* instance address of abort function i 


The SetAbortProc function sets the application-defined procedure that 
allows a print job to be canceled during spooling. This function replaces the 
SETABORTPROC printer escape for Windows version 3.1. 


- Parameters hdc 
Identifies the device context for the print job. 

abrtprc | 
Specifies the procedure-instance address of the callback function. The address 
must have been created by using the MakeProcInstance function. For more in- 
formation about the callback function, see the description of the AbortProc 
callback function. 


Return Value The return value is greater than zero if the function is successful. Otherwise, it is 
less than zero. ee 


— See Also AbortDoc, AbortProc, Escape 


SetActiveWindow ; 


HWND SetActiveWindow(hwnd) | 
HWND hwnd; /* handle of window to activate */ 


The SetActiveWindow function makes the specified top-level window the active 
window. Pet ag 
Parameters hwnd 


Identifies the top-level window to be activated. 


Return Value — The return value identifies the window that was previously active, if the function 
is successful. 


816 SetBitmapBits 


— Comments The SetActiveWindow function should be used with care, since it allows an appli- 
cation to arbitrarily take over the active window and input focus. Normally, Win- — 
dows takes care of all activation. 


See Also GetActiveWindow, SetCapture, SetFocus 


SetBitmapBits : es, FR] 


LONG SetBitmapBits(hbmp, cBits, lpvBits) 


HBITMAP hbmp; /* handle of bitmap */ 
DWORD cBits; /* number of bytes in bitmap array i 
const void FAR* I[pvBits; /* address of array with bitmap bits i 
The SetBitmapBits function sets the bits of the given bitmap, to the specified bit 
values. 
Parameters hbmp 
Identifies the bitmap to be set. 
cBits 


Specifies the number of bytes pointed to by the /pvBits parameter. 


lpvBits 
Points to an array of bytes for the bitmap bits. 


Return Value The return value is the number of bytes used in setting the bitmap bits, if the func- 
tion is successful. Otherwise, the return value is zero. 


See Also - GetBitmapBits 


setBitmapDimension | _ | | 2.x | 


DWORD SetBitmapDimension(hbmp, nWidth, pee 
HBITMAP hbhmn: /* handle of hitman 

int nWidth; /* bitmap width a‘ 

int nHeights /* bitmap height **/ 


The SetBitmapDimension function assigns a width and height to a bitmap, in 0.1- 
millimeter units. The graphics device interface (GDI) does not use these values ex- 
cept to return them when an application calls the GetBitmapDimension function. 


Parameters 


Return Value 


See Also 


SetBitmapDimensionEx 817 


hbmp 
Identifies the bitmap. 


nWidth 
Specifies the bitmap width, in 0.1-millimeter units. 


nHeight 3 
Specifies the bitmap height, in 0.1-millimeter units. 


The return value is the dimensions of the previous bitmap, in 0.1-millimeter units, 
if the function is successful. The low-order word contains the previous width; the 
high-order word contains the previous height. 


GetBitmapDimension 


SetBitmapDimensionEx BA 


BOOL SetBitmapDimensionEx(hbm, nX, nY, [pSize) 


HBITMAP hbm; 
int 1X; 

int nY;3 

SIZE FAR®* IpSize; 


- Parameters | 


/* handle of bitmap 3 ie 
/* bitmap width sa | 
/* bitmap height af 
/* address of structure for prev. imeniOns a 


The SetBitmapDimensionEx function assigns the preferred size to a bitmap, in 
0.1-millimeter units. The graphics device interface (GDI) does not use these 
values, except to return them when an application calls the GetBitmap- 
DimensionEx function. 


hbm 
Identifies the bitmap. 


nX 
Specifies the width of the bitmap, in 0.1-millimeter units. 


ny 


Specifies the height of the bitmap, in 0.1-millimeter units. 


[pSize 
Points to a SIZE structure. The previous bitmap dimensions are placed in this 
structure. If lpSize is eee nothing 1 1S returned. The SIZE structure has the fol- 
lowing form: | | 


typedef struct tagSIZE { 
int cx; 
int cy; | 

} SIZE; 


818 SetBkColor 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


setBkColor a [2x | 


COLORREF SetBkColor(hdc, clrref) 
HDC hdc; /* handle of device context */ 
COLORREF cirref;. —_—/* color specification **/ 


The SetBkColor function sets the current background color to the specified color. 


Parameters hdc 
Identifies the device context. 


clrref 
Specifies the new background aie 


Return Value The return value is the RGB value of the previous background color, if the func- 
| tion is successful. The return value is 0x80000000 if an error occurs. 


Comments If the background mode is OPAQUE, the system uses the background color to fill 
the gaps in styled lines, the gaps between hatched lines in brushes, and the back- 
ground in character cells. The system also uses the background color when con- 
verting bitmaps between color and monochrome device contexts. , 


If the device cannot display the specified color, the system sets the background 
color to the nearest physical color. 


For information about color-bitmap conversions, see the descriptions of the BitBlt 
and StretchBit functions. 


Example —, The following example uses the GetBkColor function to determine whether the 
current background color is white. If it is, the SetBkColor function sets it to red. 


DWORD dwBackColor 


dwBackColor = GetBkColor(hdc); 

if (dwBackColor == RGB(255, 255, 255)) { /* if color is white */ 
SetBkColor(hdc, RGB(255, @, @)); /* sets color to red */ 
TextOut(hdc, 100, 200, "SetBkColor test.", 16); 


SetBkMode 819 


See Also BitBIt, GetBkColor, GetBkMode, SetBkMode, StretchBIt 


SetBkMode Ol (it* ans ax 


int SetBkMode(hdc, fnBkMode) — 
HDC hdc; /* handle of device context */ 
int nBkMode; /* background mode TE 


The SetBkMode function sets the specified background mode. The background 
mode defines whether the system removes existing background colors on the draw- 
ing surface before drawing text, hatched brushes, or any pen style that is not a 
solid line. | 


Parameters hdc 
Identifies the device context. 
jnBkMode 
Specifies the background mode to be set. This parameter can be one of the fol- 
lowing values: 


Value Meaning 
OPAQUE... Background is filled with the current background color before 


the text, hatched brush, or pen is drawn. This is the default 7 
_ background mode. 


TRANSPARENT Background is not changed before drawing. 


Return Value The return value is the previous background mode, if the function is successful. 

Example sy The following example determines the current background mode by calling the 
GetBkMode function. If the mode is OPAQUE, the SetBk Mode function sets it 
to TRANSPARENT. 


int nBackMode; 


nBackMode = GetBkMode(hdc); 

if (nBackMode == OPAQUE) { 
TextOut(hdc, 90, 100, “This packeronne mode is OPAQUE. ", 31); 
SetBkMode(hdc, TRANSPARENT); | : 

poe a 7 


See Also” - GetBkColor, GetBkMode, SetBkColor 


820 SetBoundsRect 


SetBoundsRect 


UINT SetBoundsRect(hdc, l[prcBounds, flags) 


HDC hdc; 


/* handle of device context ** / 


const RECT FAR* lprcBounds; /* address of structure for rectangle i | 


UINT flags; 


Parameters 


Return Value 


/* specifies information to return */ 


The SetBoundsRect function controls the accumulation of bounding-rectangle in- 
formation for the specified device context. 


hdc 
Identifies the device context to accumulate bounding rectangles for. 


lprcBounds 
Points to a RECT structure that is used to set the bounding rectangle. Rectangle 
dimensions are given in logical coordinates. This parameter can be NULL. The 
RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 

flags 
Specifies how the new rectangle will be combined with the accumulated 
rectangle. This parameter may be a combination of the following values: 


Value | Meaning 


. DCB_ACCUMULATE Add the rectangle specified by the /prcBounds parame- 
| ter to the bounding rectangle (using a rectangle union 
operation). 
DCB_DISABLE _ Turn off bounds accumulation. 


DCB_ENABLE > Turn on bounds accumulation. (The default setting for _ 
bounds accumulation is disabled.) 


The return value is the current state of the bounding rectangle, if the function is 


encceaccfil | L tba tha flvnane naramatar tha raturn wali n ha a nn ey es nts nF tha 
BAY ULIY JEU HY PULULLIVEUL, LLY LULU V aLtue Cai uvVu COMmuliauOl Wh ULL 


following values: 


Value | Meaning 


DCB_ACCUMULATE The bounding rectangle is not empty. (This value will 
always be set.) 


Comments 


See Also 


SetBrushOrg 


SetBrushOrg 821 


Value Meaning | 
DCB_DISABLE Bounds accumulation is off. © 
DCB_ENABLE Bounds accumulation is on. 


Windows can maintain a bounding rectangle for all drawing operations. This 
rectangle can be queried and reset by the aupeaton, The drawing bounds are use- 
ful for invalidating bitmap caches. | 


GetBoundsRect 


DWORD SetBrushOrg(hdc, nXOrg, nYOrg) 


HDC hdc; 
int nXOrg; 
int nYOrg; 


Parameters 


Return Value | 


Comments 


/* handle of device context = */ 
/* x-coordinate of new origin */ 
/* y-coordinate of new origin *) 


The SetBrushOrg function specifies the origin that GDI will assign to the next 
brush an application selects into the specified device context. 


hdc 
Identifies the device context. 


nX Org 
Specifies the x-coordinate, in device units, of the new origin. This value must 
be in the range 0 through 7. 

nYOrg | 
Specifies the y-coordinate, in device units, of the new origin. This value must 
-be in the range 0 through 7. | 


The return value is the coordinates, in device units, of the previous origin, if the 


function is successful. The low-order word contains the x-coordinate; the high-- 


order word contains the y-coordinate. 


The default coordinates for the brush origin are (0, Q). 


To alter the origin of : a brush, an 1 application should call the UnrealizeObject func- 


tion, specifying the handle of the brush for which the origin will be set; call. 


— SetBrushOrg; and then call the perect nest function to select the brush into the - 
device context. 


_. The SetBrushOrg fundtion should not be used with stock bjects. 


822 SetCapture 


Example 


See Also 


-SetCapture 


The wjollosing example uses the SetBrushOrg function to shift the brush origin 
vertically by 5 pixels: 


HBRUSH hbr, hbrOld; 
SetBkMode(hdc, TRANSPARENT) ; | 
hbr = CreateHatchBrush(HS_CROSS, RGB(@, @, @)); 


UnrealizeObject(hbr); 
SetBrushOrg(hdc, @, @); 
hbrOld = SelectObject(hdc, hbr); 


Rectangle(hdc, @, 0, 200, 200); 


~hbr = SelectObject(hdc, hbrOld); /* deselects hbr */ 


UnrealizeObject(hbr); /* resets origin next time hbr selected */ 
SetBrushOrg(hdc, 3, 5); 

hbrOld = SelectObject(hdc, hbr); /* selects hbr again */ 
Rectangle(hdc, @, 0, 200, 200); 


SelectObject(hdc, hbrQld); 
DeleteObject(hbr); 


GetBrushOrg, SelectObject, UnrealizeObject 


[ 2.x | 


HWND SetCapture(hwnd) 


HWND hwnd; 


Parameters 


Comments 


/* handle of window to receive all mouse messages i 


The SetCapture function sets the mouse capture to the specified window. With 
the mouse capture set to a window, all mouse input is directed to that window, re- 
gardless of whether the cursor is over that window. Only one window can have the 
mouse capture at a time. 


hwnd : 
Identifies the window that is to receive all mouse messages. 
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_ input, if the Pa ie is successful. It is NULL if there is no such window. 


When the window no longer requires all mouse input, the application should call 
the ReleaseCapture function so that other windows can receive mouse input. 


— SetCaretPos 823 


See Also ReleaseCapture 


SetCaretBlinkTime a Pex] 
void SetCaretBlinkTime(uMSeconds) | 
UINT uMSeconds; /* blink rate in milliseconds */ 


The SetCaretBlinkTime function sets the caret blink rate. The blink rate 1S the 
elapsed time, in mUESCOnCS, between caret flashes. | 3 


Parameters uM Seconds | 
Specifies the new blink rate, in milliseconds. 


Return Value This function does not return a value. 


Comments The caret flashes on or off every uMSeconds milliseconds. One complete flash 
(off-on) takes twice uMSeconds milliseconds. 


The caret is a shared resource. A window should set the caret blink rate only if it 
owns the caret. It should restore the previous rate before it loses the input focus or 
pomcs inactive. 


See Also GetCaretBlinkTime 


SetCaretPos es : errs 
void SetCaretPos(x, y) | | 


intx; _/* horizontal position sa | 
int y; /* vertical position or 


The SetCaretPos function sets the position of the caret. 


Parameters $x  — | e 
ee ee Specifies the new x-coordinate, in client coordinates, of the caret. 


Specifies the new y-coordinate, in client coordinates, of the caret. — 


Return Value | This function does not return a value. ; 


824 SetClassLong 


Comments 


The SetCaretPos function moves the caret only if it is owned by a window in the 
current task. SetCaretPos moves the caret whether or not the caret is hidden. 


_ The caret is a shared resource. A window should not move the caret if it does not 


See Also 


SetClassLong 


own the caret. 


-GetCaretPos 


LONG SetClassLong(hwnd, nIndex, nVal) 


HWND hwnd; /* handle of window */ 
int nindex; /* index of value to change */ 
LONG nVal; /* new value */ 


Parameters 


Return Value 


Comments 


The SetClassLong function sets a long value at the specified offset into the extra 
class memory for the window class to which the specified window belongs. Extra 
class memory is reserved by specifying a nonzero value in the cbCIsExtra mem- 
ber of the WNDCLASS structure used with the RegisterClass function. 


hwnd 


Identifies the window. 


nIndex 
Specifies the zero-based byte offset of the long value to change. Valid values 
are in the range zero through the number of bytes of class memory, minus four. | 
(For example, if 12 or more bytes of extra class memory were specified, a value 
of 8 would be an index to the third long integer.) This parameter can also be 
GCL_WNDPROC, which sets a new long pointer to the window procedure. 


—nval 


Specifies the replacement value. 


The return value is the previous value of the specified long integer, if the function 
is successful. Otherwise, it is zero. 


_ If the SetClassLong function and GCL_ WNDPROC index are used to set a win- 


daw nrocedure., the snecified window nracedure must have the window-nrocedure 


form and be exported i in the module-definition file. For more information, see the 


description of the RegisterClass function. 


Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the 
window class that affects all windows subsequently created by using the class. 


— SetClassWord 825 


Applications should not call SetClassLong with the GCL_MENUNAME value. 
To access any extra 4-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/ndex parameter, 


starting at O for the first 4- -byte value in the extra space, 4 for the next 4-byte 
value, and so on. 


See Also GetClassLong, RegisterClass, SetClassWord | 


SetClassWord | 2x | 


WORD SetClassWord(hwnd, nIndex, wNewWord) 


HWND hwnd; /* handle of window */ 
int nindex; /* index of value to change i 
WORD wNewWord; /* new value */ 


The SetClassWord function sets a word value at the specified offset into the extra 
class memory for the window class to which the given window belongs. Extra 
class memory is reserved by specifying a nonzero value in the cbCIsExtra mem- 
ber of the WNDCLASS structure used with the RegisterClass function. 


Parameters hwnd | 
Identifies the window. 


nindex 
Specifies the zero-based byte offset of the word value to change. Valid values 


are in the range zero through the number of bytes of class memory, minus two 
(for example, if 10 or more bytes of extra class memory were specified, a value 
of 8 would be an index to the fifth integer), or one of the following values: 


Value | Meaning 


GCW_HBRBACKGROUND Sets a new handle of a background brush. 


GCW_HCURSOR Sets anew handle of a cursor. 
_ GCW_HICON ~ Sets a new handle of an icon. 
GCW_STYLE Sets a new style bit for the window class. 
wNewWord 


eee the replacement value. 


Return Value The return value i is the previous value of the specified word, if the function iS 
successful. Otherwise, it is zero. 


826 SetClipboardData 


Comments The SetClassWord function should be used with care. For example, it is possible 
to change the background color for a class by using SetClassWord, but this 
change does not cause all windows belonging to the class to be repainted immedi- 
ately. Applications should not attempt to set the class word values of any class at- 
tribute except those listed for the n/ndex parameter. 


To access any extra 2-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/ndex parameter, 
starting at O for the first 2-byte value in the extra space, 2 for the next 2-byte 
value, and so on. 


See Also GetClassWord, RegisterClass, SetClassLong 


SetClipboardData Pex] 


HANDLE SetClipboardData(uFormat, hData) 
UINT uFormat; /* clipboard format */ 
HANDLE hData; /* data handle * 


The SetClipboardData function sets the data in the clipboard. The application 
must have called the OpenClipboard function before calling the SetClipboard- 
Data function. 


Parameters uFormat 
Specifies the format of the data. It can be any one of the system-defined for- 
mats or a format registered by the RegisterClipboardFormat function. For a 
list of system-defined formats, see the following Comments section. 


hData 
Identifies the data to be placed in the clipboard. For all formats except 
CF_BITMAP and CF_PALETTE, this parameter must be a handle of the 
memory allocated by the GlobalAlloc function. For CF_BITMAP format, the 
hData parameter is a bitmap handle (see the description of the LoadBitmap 
function). For the CF_PALETTE format, hData is a palette handle we the de- 
scription of the CreatePalette function). 


If this parameter is NULL, the owner of the clipboard will be sent a 
WM_RENDERFORMAT message when it must supply the data. 


Return Value The return value is a handle of the data, if the function is successful. Otherwise, it 
is NULL. | 


Comments 


SetClipboardData 827 


If the hData parameter contains a handle of the memory allocated by the 
GlobalAlloc function, the application must not use this handle once it has called 
the SetClipboardData function. 


Following are the system-defined clipboard formats: 


Value 


CF_BITMAP 
CF_DIB 


CF DIF 
CF_DSPBITMAP 


CF_DSPMETAFILEPICT 


CF_DSPTEXT 


CF_METAFILEPICT 


-CF_OEMTEXT 


CF_OWNERDISPLAY 


~CF_PALETTE 


CF_PENDATA 


CF_RIFF 
CF_SYLK 
CF_TEXT 


CF_TIFF 
CF_WAVE 


Meaning 


The data is a bitmap. 


The data is a memory object containing a 
BITMAPINFO structure followed by the bitmap data. 


The data is in Data Interchange Format (DIF). 


The data is a bitmap representation of a private format. 
This data is displayed in bitmap format in lieu of the pri- 
vately formatted data. | 

The data is a metafile representation of a private data 
format. This data is displayed in metafile-picture format 
in lieu of the privately formatted data. | 

The data is a textual representation of a private data for- 
mat. This data is displayed in text format in lieu of the 
privately formatted data. 


The data is a metafile (see the description of the META- 


FILEPICT structure in the Microsoft Windows Pro- 
grammer’s Reference, Volume 3). 


The data is an array of text characters in the OEM char- 
acter set. Each line ends with a carriage return—linefeed 
(CR-LF) combination. A null character signals the end 
of the data. 


The data is ina private format that the clipboard owner 
must display. 


The data is a color palette. 


The data is for the pen extensions to the Windows oper- 
ating system. 


The data is in Resource Interchange File Format (RIFF). 
The data is in Microsoft Symbolic Link (SYLK) format. . 
The data is an array of text characters. Each line ends 


- with a carriage return—linefeed (CR-—LF) combination. A 


null character signals the end of the data. | 
The data is in Tag Image File Format (TIFF). 


The data describes a sound wave. This is a subset of the 
CF_RIFF data format; it can be used only for RIFF 


WAVE files. 


Private data formats in the range CF_PRIVATEFIRST through 


CF_PRIVATELAST are not automatically freed when the data is removed from 
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the clipboard. Data handles associated with these formats should be freed upon re- 
ceiving aWM_DESTROYCLIPBOARD message. 


Private data formats in the range CF_GDIOBJ FIRST through CF GDIOBJLAST 
will be automatically removed by a call to the DeleteObject function when the 
data is removed from the clipboard. 


If Windows Clipboard is running, it will not update its window to show the data 
placed in the clipboard by the SetClipboardData until after the CloseClipboard 
function is called. 


— See Also CloseClipboard, GetClipboardData, GlobalAlloc, OpenClipboard, 
RegisterClipboardFormat 


setClipboardViewer  B] 


HWND SetClipboard Viewer(hwnd) 
HWND hwnd; __/* handle of clipboard viewer | 


The SetClipboard Viewer function adds the given window to the chain of win- 
dows that are notified (by means of the WM_DRAWCLIPBOARD message) 
whenever the contents of the clipboard are changed. 


Parameters hwnd 
| Identifies the window to receive clipboard-viewer chain messages. 


Return Value The return value is the handle of the next window in the clipboard-viewer chain, if 
the function is successful. 


Comments | Applications should save this handle in static memory and use it when responding 
to clipboard-viewer chain messages. 


Windows that are part of the clipboard-viewer chain must respond to | 
WM_CHANGECBCHAIN, WM_DRAWCLIPBOARD, and WM_DESTROY 
messages. 


To remove itself from the clipboard-viewer chain, an application must call the 
ChangeClipboardChain function. 


See Also | ChangeClipboardChain, GetClipboard Viewer 
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SetCommBreak fax] 


int SetCommBreak(idComDev) 
int idComDey; /* device to suspend 6 


The SetCommBreak function suspends character transmission and places the 
communications device in a break state. 


_ Parameters: idComDev 
Specifies the communications device to be suspended. The OpenComm func- 
tion returns this value. 


Return Value The return vaiue is zero if the function is successful. Otherwise, it is less than zero. 


Comments The communications device remains suspended until the appucaen calls the 
ClearCommBreak function. 


See Also. ClearCommBreak, OpenComm 


SsetCommeEventMask rie 3 | | 2.x | 


UINT FAR* SetCommEventMask(idComDev, fuEvtMask) 
int idComDev; /* device to enable */ 
UINT fuEviMask; — /* events to enable =] 


The SetCommEventMask function enables events in the event word of the 
specified communications device. 


Parameters idComDev 
Specifies the communications device to be enabled. The OpenComm function 
returns this value. : 


fuEvtMask | 
Specifies which events are to be enabled: This parameter can be any combina- 
tion of the following values: 


Value | Meaning 

EV._ BREAK Set when a break is detected on input. 

EV_CTS ' Set when the CTS (clear-to-send) signal changes state. 
EV_CTSS Set to indicate the current state of the CTS signal. 


EV_DSR Set when the DSR (data-set-ready) signal changes state. 
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Value Meaning 

EV_ERR Set when a line-status error occurs. Line-status errors are 
CE_FRAME, CE_OVERRUN, and CE_RXPARITY. 

EV_PERR Set when a printer error is detected on a parallel device. Errors 
are CE_DNS, CE_IOE, CE_LOOP, and CE_PTO. 

EV_RING Set to indicate the state of ring indicator during the last modem 
interrupt. 

EV_RLSD Set when the RLSD (receive-line-signal-detect) sipnal changes 
state. 

EV_RLSDS Set to indicate the current state of the RLSD signal. 

EV_RXCHAR Set when any character is received and placed in the receiving 
queue. | 

EV_RXFLAG Set when the event character is received and placed in the re-- 


ceiving queue. The event character is specified in the device’s 
control block. 


EV_TXEMPTY Set when the last character in the transmission queue is sent. 


Return Value The return value is a pointer to the event word for the specified communications 
device, if the function is successful. Each bit in the event word specifies whether a 
given event has occurred. A bit is 1 if the event has occurred. 


Comments Only enabled events are recorded. The GetCommEventMask function retrieves: 
and clears the event word: 


See Also GetCommEventMask, OpenComm 
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int SetCommState(/pdcb) : i 
const DCB FAR* Ipdcb; /* address of device control block a 


The SetCommState function sets a communications device to the state specified 
by a device control block. 


Paramotore Indch 
| Points to a DCB structure that contains the desired communications settings for 


the device. The Id member of the DCB structure must identify the device. The 
DCB s structure has the none form: . 
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typedef struct tagDCB /* dcb * / 
{ 
BYTE Id; /* internal device identifier « / 
- UINT BaudRate; /* baud rate * / 
BYTE ByteSize; /* number of bits/byte, 4-8 * / 
BYTE Parity; /* @-4=none,odd,even,mark,space * / 
BYTE StopBits; /* @,1,2 = 1, 1.5, 2 * / 
UINT RisTimeout; /* timeout for RLSD to be set a / 
UINT CtsTimeout; /* timeout for CTS to be set a / 
UINT DsrTimeout; /* timeout for DSR to be set 2 / 


UINT fBinary :1; /* binary mode (skip EOF check) * / 
UINT fRtsDisable 2:1; /* don't assert RTS at init time */ 
UINT fParity :1; /* enable parity checking * / 
UINT fOutxCtsFlow 21; /* CTS handshaking on output * / 
UINT fOutxDsrFlow 21; /* DSR handshaking on output * / 
UINT fDummy 72; /* reserved : * /. 
UINT fDtrDisable 2:1; /* don't assert DIR at init time * / 
UINT fOutx :1;  /* enable output XON/XOFF « / 
UINT fInXx :1; /* enable input XON/XOFF * / 
UINT fPeChar :1;  /* enable parity err replacement ¥*/ 
UINT fNul] :1; /* enable null stripping Ho 2 / 
UINT fChEvt :1;  /* enable Rx character event * / 
UINT fDtrflow :1; /* DTR handshake on input * / 
UINT fRtsflow :1;  /* RTS handshake on input a / 
UINT fDummy2 21s : 

char XonChar; /* Tx and Rx XON character * / 
char XoffChar; /* Tx and Rx XOFF character 2 / 
UINT XonLim; /* transmit XON threshold — * / 
UINT XoffLim; /* transmit XOFF threshold * / 
char PeChar; /* parity error replacement char * / 
char EofChar; /* end of Input character © * / 
char EvtChar; /* received event character 2 / 
UINT TxDelay; /* amount of time between chars * / 


} DCB; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. : 


Return Value The return value is zero if the function is successful. Otherwise, it is less than zero. ° 


Example The following example uses the BuildCommDCB and SetCommState functions 
to set up COM1 at 9600 baud, no parity, 8 data bits, and 1 stop bit: | 


832 % SetCursor 


Comments 


See Also 


SetCursor 


idComDev = OpenComm("COM1", 1024, 128); 


if (idComDev < 0) { 
ShowError(idComDev, “OpenComm") ; 
return @; 
} 
err = BuildCommDCB("C0OM1:9600,n,8,1", &dcb); 
if (err < 0) { 
ShowError(err, “BuildCommDCB") ; 
return Q; 1 
} 


err = SetCommState(&dcb); 

if (err < @) { | 

ShowError(err, "SetCommState") ; 
return @; 

} : 


This function reinitializes all hardware and controls as defined by the DCB struc- 
ture, but it does not empty transmission or receiving queues. 


GetCommState 


HCURSOR SetCursor(hcur) 


HCURSOR hcur; 


‘Parameters 


Return Value 


Comments 


/* handle of cursor */ 


The SetCursor function changes the given cursor. 


heur 
Identifies the cursor resource. The resource must have been loaded by using the 
LoadCursor function. If this parameter is NULL, the cursor is removed from 
the screen. 


The return value is the handle of the previous cursor, if the function is successful. | 
It is NULL if there is no previous cursor. 


The cursor is set only if the new cursor is different from the previous cursor; other- 
wise, the function returns immediately. The function is quite fast if the new cursor 
is the same as the old. _ | 
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The cursor is a shared resource. A window should set the cursor only when the cur- 
sor is in the window’s client area or when the window is capturing all mouse 

input. In systems without a mouse, the window should restore the previous cursor 
before the cursor leaves the client area or before the window a control 
to another window. 


Any application that must set the cursor while it is in a window must ensure that 
the class cursor for the given window’s class is set to NULL. If the class cursor is 
not NULL, the system restores the previous shape each time the mouse is moved. 


See Also GetCursor, LoadCursor, ShowCursor 


SetCursorPos [ax] 


void SetCursorPos(x, y) 
int x; /* horizontal position ca 
int y; /* vertical position a 


The SetCursorPos function sets the position, in screen coordinates, of the cursor. 
If the new coordinates are not within the screen rectangle set by the most recent 
ClipCursor function, Windows automatically adjusts the coordinates so that the 
cursor stays within the rectangle. 


Parameters x 
Specifies the new x-coordinate, in screen coordinates, of the cursor. 
2 e t) ° e e ‘ +a 
Specifies the new y-coordinate, in screen coordinates, of the cursor. 
Return Value This function does not return a value. 
Comments The cursor is a shared resource. A window should move the cursor only when the 


cursor is in its client area. 


See Also - ClipCursor, GetCursorPos 
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int SetDIBits(hdc, hbmp, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse) 


HDC hdc; /* handle of device context 

HBITMAP hbmp; /* handle of bitmap a) 

UINT uStartScan; /* starting scan line */ 

UINT cScanLines; /* number of scan lines */ 

const void FAR* IpvBits; /* address of array with bitmap bits a 

BITMAPINFO FAR? [pbmi; /* address of structure with bitmap data a 

— UINT fuColorUse; /* type of color indices to use | a 

The SetDIBits function sets the bits of a bitmap to the values given in a device- 
independent bitmap (DIB) specification. 

Parameters hdc 


Identifies the device context. 
hbmp 

Identifies the bitmap to set the data in. 
uStartScan 


Specifies the zero-based scan number of the first scan line in the buffer pointed 
to by the /pvBits parameter. , 


cScanLines 
Specifies the number of scan lines in the /pvBits buffer to copy into the bitmap 
identified by the hbmp parameter. 


lpvBits 
Points to the device-independent bitmap bits that are stored as an array of bytes. 
The format of the bitmap values depends on the biBitCount member of the 
_ BITMAPINFOHEADER structure, which is the first member of the 
~ BITMAPINFO structure pointed to by the Jpbmi parameter. 


The BITMAPINFOHEADER structure has the following form: 
typedef struct tagBITMAPINFOHEADER { /* bmih */ 
DWORD biSize; 
LONG biWidth; 
LONG biHeight; 
WORD biPlanes; 
WORD biBitCount; 
DWORD. biCompression; 
DWORD biSizeImage; 
LONG bixPelsPerMeter; 
LONG biYPelsPerMeter; 
DWORD biClrUsed; 
DWORD biCirImportant; 
} BITMAPINFOHEADER; 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


lpbmi 
Points to a BITMAPINFO structure that contains information about the device- 
independent bitmap. The BITMAPINFO structure has the following form: 


typedef struct tagBITMAPINFO { /#* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD | bmiColors[1]; 

-} BITMAPINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


JjuColorUse 
Specifies whether the bmiColors member of the BITMAPINEFO structure con- 
tains explicit RGB values or indices into the currently realized logical palette. 
This parameter must be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array of 16-bit indices into | 
| the palette of the device context identified by the hdc pa- 
rameter. 


DIB_RGB_COLORS The color table contains literal RGB values. 


Return Value The return value is the number of scan lines copied, if the function is successful. 
Otherwise, it is zero. 


Comments The bitmap identified by the hbmp parameter must not be selected into a device 
context when the application calls this function. 


To reduce the amount of memory required to set bits from a large device- 
independent bitmap on a device surface, an application can band the output by re- 
peatedly calling the SetDIBitsToDevice function, placing a different portion of 
the entire bitmap into the /pvBits buffer each time. The values of the uStartScan 
and cScanLines parameters identify the portion ob the entire bitmap that is con- 
tained in the [pvBits buffer. 


The origin of a device-independent bitmap is the bottom-left corner of the bitmap, 
not the top-left corner, which is the origin when the mapping mode is MM_TEXT. 
GDI performs the necessary transformation to display the image correctly. 


See Also  SetDIBitsToDevice 
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‘SetDIBitsToDevice : a 


int SetDIBitsToDevice(hdc, XDest, YDest, cx, cy, XSrc, YSrc, uStartScan, cScanLines, lpvBits, Ipbmi, 


fuColorUse) 
HDC hdc; /* handle of device context _ + 
int XDest; /* x-coordinate origin of destination rect sa 
int YDest; /* y-coordinate origin of destination rect a 

int cx3 | /* rectangle width */ 

int cy; /* rectangle height ‘a 

int XSrc3 /* x-coordinate origin of source rect a 

int YSrc; | /* y-coordinate origin of source rect 4 | 

UINT uStartScan; _ /* number of first scan line in array i 

UINT cScanLines; /* number of scan lines */ 

void FAR* IpvBits; /* address of array with DIB bits a | 

BITMAPINFO FAR® [pbmi; /* address of structure with bitmap info | a 

UINT fuColorUse; /* RGB or palette indices **/ 
The SetDIBitsToDevice function sets bits from a device-independent bitmap 
(DIB) directly on a device surface. The device coordinates specified define a 
rectangle within the total bitmap. SetDIBitsToDevice sets the bits in this rectangle 
directly on the display surface of the output device associated with the given 
device context, at the specified logical coordinates. 

Parameters hdc 

Identifies the device context. 
XDest 
Specifies the logical x-coordinate of the origin of the destination rectangle. 

YDest 


Specifies the logical y-coordinate of the origin of the destination rectangle. 


Cx 
Specifies the x-extent, in device units, of the rectangle in the bitmap. 
cy | | 
Specifies the y-extent, in device units, of the rectangle in the bitmap. 
XSrc 

Specifies the x-coordinate, in device units, of the source rectangle in the bitmap. 
YSrc | | 
_ Specifies the y-coordinate, in device units, of the source rectangle in the bitmap. 
uStartScan | 


Specifies the scan-line number of the device-independent bitmap that is con- _ 
_ tained in the first scan line of the buffer pointed to by the /pvBits parameter. 


cScanLines — | 
Specifies the number of scan lines in the /pvBits buffer to copy to the device. 


Return Value 


Comments 


See Also 
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lpvBits 
Points to the DIB bits that are stored as an array of ee 

lpbmi 
Points to a BITMAPINFO structure that contains information about the bit- 
map. The BITMAPINFO structure has the following form: 


typedef struct tagBITMAPINFO { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 

} BITMAPINFO; | 


For a full description of this structure, see the POSED Windows ponte 
mer’s Reference, Volume 3. 

fuColorUse 
Specifies whether the bmiColors member of the [pbmi parameter contains ex- 
plicit RGB values or indices into the currently realized logical palette. This pa- 
rameter must be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array of 16-bit indices into 
the currently realized logical palette. 


DIB_RGB_ COLORS The color table contains literal RGB values. 


The return value is the number of scan lines set, if the function is successful. 


The origin of a device-independent bitmap is the bottom-left corner of the bitmap, 
not the top-left corner, which is the origin when the mapping mode is MM_TEXT. 
GDI performs the necessary transformation to display the image correctly. 


To reduce the amount of memory required to set bits from a large device- 
independent bitmap on a device surface, an application can band the output by re- 


__peatedly calling SetDIBitsToDevice, placing a different portion of the entire 


bitmap into the /pvBits buffer each time. The values of the uStartScan and cScan- 
Lines parameters identify the portion of the entire bitmap that is contained in the 
[pvBits buffer. - 
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SetDigltemint 


void SetDigItemInt(hwndDig, idControl, uValue, fSigned) 


HWND hwndDie; /* handle of dialog box +) 
int idControl; /* identifier of control sa Mie 
UINT uValue; /* value to set */ 
BOOL fSigned; /* signed or unsigned indicator */ 
The SetDigItemInt function sets the text of a given control in a dialog box to the 
string representation of a specified integer value. 
Parameters hwndDlg 
| Identifies the dialog box that contains the control. 
idControl 
Specifies the control to be changed. 
uValue 7 
Specifies the integer value used to generate the item text. 
fSigned . | 


Return Value 
‘Comments 


See Also 


SetDigitemText 


Specifies whether the uValue parameter is signed or unsigned. If this parameter 
is TRUE, uValue is signed. If this parameter is TRUE and uValue is less than 
zero, a minus sign is placed before the first digit in the string. If this parameter 
is FALSE, uValue is unsigned. 

This function does not return a value. 


SetDigItemInt sends a WM_SETTEXT message to the given control. 


GetDigItemInt, SetDigitemText 


void SetDlgItemText(hwnaDle, idControl, lpsz) 


HWND hwndDig; 
int idControl; 
LECOLN [pysz; 


‘Parameters 


/* handle of dialog box */ 
/* identifier of control */ 
/* iexi to set 


_ The SetDigitemText function sets the title or text of a control in a dialog box. 


hwndDlg 7 
Identifies the dialog box that contains the control. 


Return Value 


~ Comments 


See Also 
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idControl 
Identifies the control whose text is to be set. 


[psz | 
Points to the null-terminated string that contains the text to be copied to the con- 
trol. | 


This function does not return a value. 


The SetDigItemText function sends a WM_SETTEXT message to the given con- 
trol. | | 


GetDigitemText, SetDigItemInt 
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void SetDoubleClickTime(u/nterval) 


UINT ulnterval; 


Parameters 


Return Value 


Comments 


See Also 


/* double-click interval */ 


The SetDoubleClickTime function sets the double-click time for the mouse. A 
double-click is a series of two clicks of the mouse button, the second occurring 
within a specified time after the first. The double-click time is the maximum num- 
ber of milliseconds that may occur between the first and second clicks of a double- 
click. | : 


ulnterval 
Specifies the number of milliseconds that can occur between double-clicks. 


This function does not return a value. 


If the u/nterval parameter is zero, Windows uses the default double-click time of 
500 milliseconds. : 


The SetDoubleClickTime function alters the double-click time for all windows in 
the system. | | | 


GetDoubleClickTime 
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setErrorMode 2x | 


UINT SetErrorMode({uErrorMode) 
_UINT fuErrorMode; /* specifies the error-mode flag sa 


The SetErrorMode function controls whether Windows handles MS-DOS Inter- 
rupt 24h errors or allows the calling application to handle them. | 


Parameters fuErrorMode | 
Specifies the error-mode flag. The flag can be a combination of the following 
values: | 
Value Meaning 
SEM_FAILCRITICALERRORS Windows does not display the critical-error- 


handler message box and returns the error to 
| the calling application. 
SEM_NOGPFAULTERRORBOX Windows does not display the general-pro- 
tection-fault message box. This flag should 
be set only by debugging applications that 
handle GP faults themselves. 
SEM_NOOPENFILEERRORBOX Windows does not display a message box 
when it fails to find a file. | 


~ Return Value The return value is the previous state of the error-mode flag, if the function is 


successful. 
Example The following example uses the SetErrorMode function to turn off the file-not- 


found message box (the application handles this error itself): 


/* Turn off the "File not found" error box. */ 
SetErrorMode(SEM_NOOPENFILEERRORBOX) ; 

/* Load the TOOLHELP.DLL library module. */ 
hinstToolHelp = LoadLibrary("TOOLHELP.DLL"); 


if (hinstToolHelp > HINSTANCE_ERROR) { /* loaded successfully */ 


. /* Use the DLL here. */ 


SetFocus 841 


else { 
strcpy(szBuf, "LoadLibrary failed"); 


MessageBox(NULL, szBuf, “Library Functions", MB_ICONHAND); 
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HWND SetFocus(hwnd) 
HWND hwnd; /* handle of window to receive focus */ 


The SetFocus function sets the input focus to the given window. Alli subsequent 
keyboard input is directed to this window. The window, if any, that previously had 
_ the a focus loses it. 


Parameters hwnd | 
Identifies the window to receive the keyboard ape If this parameter is NULL, 
keystrokes are ignored. 


Return Value The return value identifies the window that previously had the input focus, if the — 
function is successful. It is NULL if there i is no such window or if the specified 
handle is invalid. | 


Comments The SetFocus function sends a WM_KILLFOCUS message to the window that 
loses the input focus and a WM_SETFOCUS message to the window that receives 
the input focus. It also activates either the window that receives the focus or the 
parent of the window that receives the focus. 


If a window is. active but does not have the focus (that is, no window 

has the focus), any key pressed will produce the WM_SYSCHAR, 
WM_SYSKEYDOWN, or WM_SYSKEYUP message. If the VK_MENU key is 
also pressed, the /Param parameter of the message will have bit 30 set. Otherwise, 
the messages that are produced do not have this bit set. 


See Also oe GetActiveWindow, GetFocus, SetActiveWindow, SetCapture 


842 SetHandleCount 


SetHandleCount 


UINT SetHandleCount(cHandles) 
UINT cHandles; /* number of file handles needed */ 


The SetHandleCount function changes the number of file handles available to a 
task. 


Parameters cHandles 
Specifies the number of file handles the application requires. This count cannot 
_be greater than 255. 


Return Value The return value is the number of file handles available to the application, if the 
function is successful. This number may be less than the number of handles 
specified. | 


‘Comments By default, the maximum number of file handles available to a task is 20. 


Example The following example uses the SetHandleCount function to set the number of 
available file handles to 30: 


UINT cHandles; 
char szBuf[80]; 


cHandles = SetHandleCount(3@); 


sprintf(szBuf, "%d handles available”, cHandles); 
MessageBox(hwnd, szBuf, "SetHandleCount", MB_OK); 


setKeyboardState a [2x | 


void Set KeyboardState([pbKeyState) 
BYTE FAR® [pbKeyState; /* address of array with virtual-key codes | 


The SetKeyboardState function copies a 256-byte array of keyboard sad states 
into the Windows keyboard-state table. 


Parameters lpbKeyState 
Points to a 256-byte array that contains keyboard key states. 


Return Value 


Comments 


Example 


See Also 
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This function does not return a value. 


In many cases, an application should call the GetKeyboardState function first to. 
initialize the 256-byte array. The application should then change the desired bytes. 


SetKeyboardState sets the LEDs and BIOS flags for the NUMLOCK, CAPSLOCK, 
and SCROLL LOCK keys according to the toggle state of the VK_NUMLOCK, 
VK_CAPITAL, and VK_SCROLL entries of the array. 


For more information, see the description of the GetKeyboardState function. 


The following example simulates the pressing of the CTRL key: 


BYTE pbKeyState[256]; 
GetKeyboardState((LPBYTE) &pbKeyState); 


pbKeyState[VK_CONTROL] |= 0x80; 
SetKeyboardState((LPBYTE) &pbKeyState); 


GetKeyboardState 
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int SetMapMode(hdc, fnMapMode) 


HDC hdc; 
int fnMapMode; 


Parameters 


/* handle of device context = 
/* mapping mode to set ei 


The SetMapMode function sets the mapping mode of the given device context. 
The mapping mode defines the unit of measure used to convert logical units to 
device units; it also defines the orientation of the device’s x- and y-axes. GDI uses 
the mapping mode to convert logical coordinates into the appropriate device 
coordinates. 


hdc | 
Identifies the device context. 


_ fnMapMode 


Specifies the new mapping 1 mode. This parameter can be any one of the follow- — 
ing values: , 
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Return Value 


Comments 


Example 


Value Meaning 


MM_ANISOTROPIC Logical units are converted to arbitrary units with 
arbitrarily scaled axes. Setting the mapping mode to 
MM_ANISOTROPIC does not change the current win- 
dow or viewport settings. To change the units, orienta- 
tion, and scaling, an application should use the 
SetWindowExt and Set ViewportExt functions. 


MM_HIENGLISH Each logical unit is converted to 0.001 inch. Positive x is 
to the right; positive y is up. 
MM_HIMETRIC Each logical unit is converted to 0.01 millimeter. Positive 
| | X is to the right; positive y is up. 
MM_ISOTROPIC Logical units are converted to arbitrary units with equally 


scaled axes; that is, one unit along the x-axis is equal to 
one unit along the y-axis. The SetWindowExt and 

Set ViewportExt functions must be used to specify the 
desired units and the orientation of the axes. GDI makes 
adjustments as necessary to ensure that the x and y units 
remain the same size. 


MM_LOENGLISH Each logical unit is converted to 0.01 inch. Positive x is 
to the right; positive y is up. 

MM_LOMETRIC Each logical unit is converted to 0.1 millimeter. Positive 
X is to the right; positive y is up. 

MM_TEXT Each logical unit is converted to one device pixel. Posi- 
tive x is to the right; positive yisdown. 

MM_TWIPS Each logical unit is converted to 1/20 of a point. (Be- 


cause a point is 1/72 inch, a twip is 1/1440 inch). Positive 
X is to the right; positive y is up. 


The return value is the previous mapping mode, if the function is successful. 


The MM_TEXT mode allows applications to work in device pixels, where one 
unit is equal to one pixel. The physical size of a pixel varies from device to device. 


The MM_HIENGLISH, MM_HIMETRIC, MM_LOEN GLISH, | | 
MM_LOMETRIC, and MM_TWIPS modes are useful for applications that must 
draw in physically meaningful units (such as inches or millimeters). 


The MM_ISOTROPIC mode ensures a 1:1 aspect ratio, which is useful when it is 
important to preserve the exact shape of an image. 


The MM_ANISOTROPIC mode allows the x- and y-coordinates to be adjusted in- 


dependently. 


The following example uses the SetMapMode function to set the mapping mode 
to MM_TWIPS and then uses the CreateFont function to create an 18-point ek 
cal font: 


See Also 


SetMapperFlags 845 


HFONT hfont, hfont0Old; 
int MapModePrevious, iPtSize = 18; 
PSTR pszFace = "MS Serif"; 


MapModePrevious = SetMapMode(hdc, MM_TWIPS); | 
hfont = CreateFont(-iPtSize * 20, @, 0, 0, 0, /* specify pt size * / 
0, 0, 0, 0, 0, @, 0, 0, pszFace); /* and face name only */ 


hfontOld = SelectObject(hdc, hfont); 
TextOut(hdc, 100, -500, pszFace, strien(pszFace)); 


SetMapMode(hdc, MapModePrevious); 
SelectObject(hdc, hfont0ld); 


DeleteObject(hfont); 


GetMapMode, Set ViewportExt, SetWindowExt 


SetMapperFlags | Ea 


DWORD SetMapperFlags(hdc, fawMatch) 


HDC hdc; 


DWORD fdwMatch; 


Parameters 


Return Value 


Comments 


/* handle of device context */ 
/* mapper flag 7 */ 


The SetMapperFlags function changes the method used by the font mapper when 
it converts a logical font to a physical font. An application can use SetMapper- 
Flags to cause the font mapper to attempt to choose only a physical font that ex- 
actly matches the aspect ratio of the specified device. 


hdc 
Identifies a device context. 


fdwMatch 
Specifies whether the font mapper attempts to match a font’ s aspect height and 
width to the device. When this value is ASPECT_FILTERING, the mapper 
selects only fonts whose x-aspect and y-aspect exactly match those of the 
specified device, and the remaining bits are ignored. 


The return value is the previous value of the font-mapper flag, if the function is 
successful. 


An application that uses only raster fonts can use the SetMapperF lags function to 
ensure that the font selected by the font mapper is attractive and readable on the 
specified device. Applications that use scalable (TrueType) fonts typically do not 

use SetMapperF lags. | 
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If no physical font has an aspect ratio that matches the specifications in the logical 
font, GDI chooses a new aspect ratio and selects a font that matches this new 
aspect ratio. 


setMenu rex] 


BOOL SetMenu(hwnd, hmenu) | 
HWND hwnd; /* handle of window ia) i 
HMENU hmenu; /* handle of menu =) 


The SetMenu function sets the given window’s menu to the specified menu. 


Parameters hwnd 
Identifies the window whose menu is to be changed. 
hmenu 


Identifies the new menu. If this parameter is NULL, the window’s current 
menu is removed. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The SetMenu function causes the window to be redrawn to reflect the menu 
change. ae 


SetMenu will not destroy a previous menu. An application should call the 
DestroyMenu function to accomplish this task. 


Example ~HMENU hmenu; 


hmenu = LoadMenu(hinst, "My Menu"); 
SetMenu( hwnd, hmenu); 


See Also : DestroyMenu, LoadMenu, LoadMenulndirect 
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SetMenultemBitmaps 


BOOL SetMenultemBitmaps(imenu, idltem, fuF lags, hbmUnchecked, hbmChecked) 


HMENU hmenu; /* handle of menu | */ 
UINT idltem; /* menu-item identifier */ 
UINT fuFlags; /* menu-item flags a 
HBITMAP hbm bnchecked: /* handle of unchecked bitmap 2) 
HBITMAP hbmChecked; /* handle of checked bitmap i 


The SetMenultemBitmaps function associates the given bitmaps with a menu 
item. Whether the menu item is checked or unchecked, Windows displays the ap- 
propriate check-mark bitmap next to the menu item. 


Parameters hmenu 
Identifies the menu. 


idIltem 
Specifies the menu item to be changed, as determined by the a lags sseaneiee 


fuFlags 
Specifies how the id/tem parameter is interpreted. This parameter can be one of 
the following values: 


Value ‘Meaning 
MF_BYCOMMAND The idltem parameter specifies the menu-item ED EMEE 
~ (default value). 7 
MF_BYPOSITION The idItem parameter specifies the zero-based position ar 
the menu item. 
hbmUnchecked 
Identifies the check-mark bitmap to display when the menu item is not sieckedl 
hbmChecked 
Identifies the check-mark bitmap to display when the menu item is checked. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments — If either the hbmUnchecked or the hbmChecked parameter is NULL, Windows 


_ displays nothing next to the menu item for the corresponding attribute. If both pa- 
~ rameters are NULL, Windows uses the default check mark when the item is 
checked and removes the check mark when the item is unchecked. 


When the menu is destroyed, these bitmaps are not destroyed; the application must 
destroy them. | 


848 SetMessageQueue 


The GetMenuCheckMarkDimensions function retrieves the dimensions of the 
default check mark used for menu items. The application should use these values 
to determine the appropriate size for the bitmaps supplied with this function. 


See Also GetMenuCheckMarkDimensions 


SetMessageQueue _ [2x | 


BOOL SetMessageQueue(cMsg) 
int cMsg; /* size of message queue = */ 


The SetMessageQueue function creates a new message queue. It is particularly 
useful in applications that require a queue that contains more than eight messages 
(the maximum size of the default queue). 


Parameters cMsg 
Specifies the maximum number of messages that the new queue may contain. 
This value must not be larger than 120. 


Return Value The return value is nonzero if the function is successful. If the value specified in 
the cMsg parameter is larger than 120, the return value is nonzero but the message 
queue is not created. The return value is zero if an error occurs. 


Comments The function must be called from an application’s WinMain function before any 
windows are created and before any messages are sent. The SetMessageQueue 
function destroys the old queue, along with messages it might contain. 


If the return value is zero, the application has no queue, because the Set- 
MessageQueue function deletes the original queue before attempting to create a 
new one. The application must continue calling SetMessageQueue with a smaller 
queue size until the function returns nonzero. 


See Also _ GetMessage, PeekMessage 
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SetMetaFileBits 2x] 


HGLOBAL SetMetaFileBits(hmf) 
HMETAFILE himf; /* handle of metafile */ 


The SetMetaFileBits function creates a memory metafile from the data in the 
given global memory object. 


Parameters hmf \ 
Identifies the global memory object that contains the metafile data. The object 
must have been created by a previous call to the GetMetaFileBits function. 


Return Value The return value is the handle of a memory metafile, if the function is successful. 
Otherwise, it is NULL. 


Comments After the SetMetaFileBits function returns, the metafile handle it returns must be 
used instead of the hmf handle to refer to the metafile. If SetMetaFileBits is 
successful, the application should not use or free the memory handle specified by - 
the nee parameter, because that handle is reused by Windows. 


When the application no longer needs the metafile header, it should free the handle 
by calling the DeleteMetaFile function. , 


See Aliso. | GetMetaFileBits, GlobalFree 


SetMetaFileBitsBetter — - ee ES 


HGLOBAL SetMetaFileBitsBetter(hm/) 
HMETAFILE himf; /* handle of the metafile i 


The SetMetaFileBitsBetter function creates a memory metafile from the data in 
the specified global-memory object. 


Parameters hmf 
| Identifies the global-memory object that contains the metafile data. The ebieet 
must have been created by a previous call to the GetMetaFileBits function. 


Return Value The return value is the handle of a memory metafile, if the function is successful. 
| Otherwise, the return value is NULL. 
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‘Comments 


See Also 


The global-memory handle returned by SetMetaFileBitsBetter is owned by GDI, 
not by the application. This enables applications that use metafiles to support ob- 
ject linking and embedding (OLE) to use metafiles that persist beyond the 
termination of the application. An OLE application should always use SetMeta- 


FileBitsBetter instead of the SetMetaFileBits function. 


After the SetMetaFileBitsBetter function returns, the metafile handle returned by — 
the function should be used to refer to the metafile, instead of the handle identified 
by the hmf parameter. 


GetMetaFileBits, SetMetaFileBits 
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UINT SetPaletteEntries(hpal, iStart, cEntries, lppe) 


HPALETTE hpai; /* handle of palette ical 
UINT iStart; /* index of first entry to set */ 
UINT cEntries; /* number of entries to set */ 
const PALETTEENTRY FAR [ppe; /* address of array of structures a 
The SetPaletteEntries function sets RGB color values and flags in a range of en- 
tries in the given logical palette. 
Parameters hpal 
| Identifies the logical palette. 
iStart 
Specifies the first logical-palette entry to be set. 
cEntries 
Specifies the number of logical-palette entries to be set. 
[ppe 


Points to the first member of an array of PALETTEENTRY structures contain- 
ing the RGB values and a The PALETTEENTRY structure has the follow- 
~ ing form: 


typedef struct tagPALETTEENTRY { /* pe */ 
BYTE peRed; 
BYTE peareen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY ; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
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Return Value = = §$The return value is the number of entries set in the logical palette, if the function is 
| successful. Otherwise, it is zero. 


~ Comments | If the logical palette is selected into a device context when the application calls the 
SetPaletteEntries function, the changes will not take effect until the application 
calls the RealizePalette function. , 


See Also | RealizePalette 


setParent ara. _ [ 2.x | 


HWND SetParent(hwndChild, hwndNewParent) 
~HWND hwndChild; /* handle of window whose parent is changing */ 
HWND hwndNewParent; _—si/* handle of new parent window sa 


The SetParent function changes the parent window of the given child window. | 


Parameters | | hwndChild 
Identifies the child window. 


hwndNewParent 
Identifies the new parent window. 


Return Value The return value is the handle of the previous parent window, if the function is 
| successful. | , 
Comments”. If the window identified by the hwndChild parameter is visible, Windows per- 


forms the appropriate redrawing and repainting. 


SeeAlso = GetParent, IsChild 


SetPixel §s lee fee, [eo] 


COLORREF SetPixel(hdc, nXPos, nYPos, clrref) 


HDC hdc; _ /* handle of device context == */_ 
intnXPos; /* x-coordinate of pixel to set 7 
int nYPos; /* y-coordinate of pixel to set — a ae 


COLORREF cirref, = /* color of set pixel | ae 


852 = SetPolyFillMode 


Parameters 


Return Value 


Comments 


See Also 


The SetPixel function sets the pixel at the specified coordinates to the closest ap- 
proximation of the given color. The point must be in the clipping region; if it is 
not, the function does nothing. 


hdc | 
Identifies the device context. 


nXPos | 
Specifies the logical x-coordinate of the point to be set. 


nYPos 
Specifies the logical y-coordinate of the point to be set. 


clrref 
Specifies the color to be used to paint the point. 


The return value is the RGB value for the color the point is painted, if the function 
is successful. This value can be different from the specified value if an approxima- 
tion of that color is used. The return value is —1 if the function fails (if the point is 

outside the clipping region). 


Not all devices support the SetPixel function. To discover whether a device sup- 
ports raster operations, an application can call the GetDeviceCaps function using 
the RC_BITBLT index. 


GetDeviceCaps, GetPixel 


SetPolyFillMode a fax | 


int SetPolyFillMode(hdc, fnMode) 


HDC hdc; 
int jnMode; 


Parameters 


Return Value © 


/* handle of device context st 
/* polygon-filling mode i 


The SetPolyFillMode function sets the specified polygon-filling mode. 


hdc 
Identifies the device context. 
Tainoae | | | 
Specifies the new filling mode. This value may be either ALTERNATE or 
WINDING. The default mode is ALTERNATE. 


The return value specifies the previous filling mode, if the function is successful. 
Otherwise, it is zero. | 


Comments 


Example 
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When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, a count is incremented (increased by 
one); when the line passes through a counterclockwise line segment, the count is 
decremented (decreased by one). The area is filled if the count is nonzero when 
the line reaches the outside of the figure. 


The following example uses winding mode to draw the same figure twice. The fig- 
ure is a rectangle that completely encloses a triangle. The first time the figure is 
drawn, both the rectangle and the triangle are drawn clockwise, and both the 
rectangle and the triangle are filled. The second time, the rectangle is drawn clock- 
wise, but the triangle is drawn counterclockwise; the rectangle is filled, but the tri- 
angle is not. (If the figures had been drawn using alternate mode, the rectangle - 
would have been filled and the triangle would not have been filled, in both cases.) 


HBRUSH hbrGray, hbrPrevious; 


/* 

* Define the points for a clockwise triangle in a clockwise 
* rectangle. 

* / 


POINT aPolyPoints[9] = {{ 50, 60 }, { 250, 60 }, { 250, 260 }, 


{ 50, 260 }, { 50, 60}, { 150, 8@ }, 
{ 230, 240 }, { 70, 240 }, { 150, 8@ }}; 


ant aPolyCountL] = { 5, 4 }; 


int cValues, i; 


hbrGray = GetStockObject(GRAY_BRUSH) ; 
hbrPrevious = SelectObject(hdc, hbrGray); 


cValues = sizeof(aPolyCount) / sizeof(int); 


SetPolyFillMode(hdc, WINDING); — /* sets winding mode */— 
poly ot gone ec aPolyPoints, aPolyCount, cValues); 


[* Define the ealangle counter-clockwise */ 


aPolyPoints[6].x = 70; ‘aPolyPoints[6].y = 240; 
aPolyPoints[7].x = = 240; 


230; aPolyPoints[7].y 
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for (i = 0; i < sizeof(aPolyPoints) / sizeof(POINT); i++) 
aPolyPoints[i].x t= 300; /* moves figure 300 units right */ 


PolyPolygon(hdc, aPolyPoints, aPolyCount, cValues); 


SelectObject(hdc, hbrPrevious); 


See Also | _ GetPolyFillMode, PolyPolygon 
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BOOL SetProp(hwnd, lpsz, hData) 


HWND hwnd; /* handle of window */ 
LPCSTR Ipsz; /* atom or address of string */ 


HANDLE hData; /* handle of data */ 


The SetProp function adds a new entry or changes an existing entry in the prop- 
erty list of the given window. The function adds a new entry to the list if the given 
character string does not exist already in the list. The new entry contains the string 
and the handle. Otherwise, the function replaces the string’s current handle with 
the given handle. 


Parameters hwnd | 
Identifies the window whose property list receives the new entry. 
[psz 
Points to a null- eaniuaeed string or an atom that identifies a string. If this pa- 
rameter is an atom, it must be a global atom created by a previous call to the 
GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low- 
order word of Ipsz; the high-order word must be zero. 


hData 
Identifies data to be conic to the property list. The data handle can identify any 
- 16-bit value useful to the application. 


Return Value The return value is nonzero if the data handle and string are added to the property 
list. Otherwise, it is zero. 
Commenis Before destroying a window (that is, before processing the WM_DESTROY mes- 
-_ - gage), an application must remove all entries it has added to the property list. The 
RemoveProp function must be used to remove entries from a property list. 


See Also GetProp, GlobalAddAtom, RemoveProp 
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[ 2x | 


void SetRect(/prc, nLeft, nTop, nRight, nBottom) 


RECT FAR* [prc; 
int nLeft; 

int nTop; 

int nRight; 

int nBottom; 


Parameters 


Return Value 


Comments 


See Also 


/* address of structure with rectangle to set | 
/* left side */ 
/* top side | - **/ 
/* right side 7 aH | 
/* bottom side | */ 


The SetRect function sets rectangle coordinates. The action of this function is 
equivalent to assigning the left, top, right, and bottom arguments to the appropriate 
members of the RECT structure. 


[prc 
Points to the RECT structure that contains the rectangle to be set. The RECT 
structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; | 
int top; 
int right; 
int bottom; 
} RECT; 


For a full secretin of this structure, see the Microsoft Windows Program- _ 
mer’s Reference, Volume 3. 


nLeft 

Specifies the x-coordinate of the upper-left corner. 
nlop 

Specifies the y-coordinate of the upper-left corner. 


nRight 
Specifies the x-coordinate of the lower-right corner. 


~ nBottom 


Specifies the y-coordinate of the lower-right comer. 
This function does not return a value. 


The width of the rectangle, specified by the absolute value of nRight - nLeft, must 


_ not exceed 32,767 units. This limit also applies to the height of the rectangle. 


CopyRect, SetRectEmpty 
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SetRectEmpty Pax] 


void SetRectEmpty(/prc) 


RECT FAR*® Iprc; /* address of struct. with ectundle to set to empty i 
The SetRectEmpty function creates an empty rectangle (all coordinates set to 
Zero). 

Parameters [prc 


Points to the RECT structure that contains the rectangle to be set to empty. The 
RECT structure has the following form: 


rypeded struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 
For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 
Return Value This function does not return a value. 


‘See Also CopyRect, SetRect 
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void SetRectRgn(hrgn, nLeftRect, nTopRect, nRightRect, nBottomRect) 


HRGN hrgn; /* handle of region sa 
int nLeftRect; /* x-coordinate top-left corner of rectangle i 
int nTopRect; /* y-coordinate top-left corner of rectangle i 
int nRightRect; /* x-coordinate bottom-right corner of rectangle i 
int nBottomRect; /* y-coordinate bottom-right corner of rectangle | 


The SetRectRgn function changes the given neztOn into a rectangular region with 
the specified coordinates. | | 


Parameters hrgn 
Identifies the region. 


_ nLeftRect 7 
Specifies the x-coordinate of the upper-left corner of the rectangular region. 
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—nTopRect 
Specifies the y-coordinate of the upper-left corner of the rectangular region. 


nRightRect 
Specifies the x-coordinate of the lower-right corner of the rectangular region. 


nBottomRect | 
Specifies the y-coordinate of the lower-right corner of the rectangular region. 


Return Value This function does not return a value. 


Comments Applications can use this function instead of the CreateRectRgn function to avoid 
a allocating more memory from the GDI heap. Because the memory allocated for 
the hrgn parameter is reused, no new allocationis performed. _ 


Example — The following example uses the CreateRectRgn function to create a rectangular 
| region and then calls the SetRectRgn function to change the region coordinates: 


HRGN hrgn; 


hrgn = CreateRectRgn(10, 10, 30, 30); 
PaintRgn(hdc, hrgn); 


SetRectRgn(hrgn, 50, 50, 150, 200); 
PaintRgn(hdc, hrgn); 


DeleteObject(hrgn) ; 


See Also CreateRectRen 


SetResourceHandler fen 8 ene — ex | 


RSRCHDLRPROC SetResourceHandler(hinst, lpszType, IpLoadProc) — 


HINSTANCE hinst; /* handle of application instance — oe i 
LPCSTR lIpszType; /* address of resource-type identifier | 
RSRCHDLRPROC [pLoadProc; /* callback procedure-instance address 7 | 
The SetResourceHandler function installs a callback function that loads re- 
, sources. : 
Parameters hinst 


Identifies the instance of the module whose executable file contains the re- 
source. 
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lpszType - a 
Points to a null-terminated string that specifies a resource type. For predefined 
resource types, the high-order word should be zero and the low-order word 
should indicate the resource type. 


[pLoadProc 
Specifies the procedure-instance sitive of the application-supplied callback 
function. For more information, see the description of the LoadProc callback 
function. 


Return Value The return value is a pointer to the previously installed resource handler, if the 
3 function is successful. If no resource handler has been explicitly installed, the re- 
turn value is a pointer to the default resource handler. 


Comments An application may find this function useful for handling its own resource types, 
but the use of this function is not required. 


The address passed as the /pLoadProc parameter must be created by using the 
MakeProclInstance function. 


| | See Also FindResource, LoadProc, LockResource, MakeProcInstance 


setROP2 [ 2.x | 


int SetROP2(hdc, fnDrawMode) 
HDC hdc; /* handle of device context al 
int nDrawMode; /* new drawing mode | 


The SetROP2 function sets the current drawing mode. The drawing mode speci- 
fies how the colors of the pen and the interior of filled objects are combined with 
the color already on the screen surface. | 


Parameters hdc 
Identifies the device context. 


jnDrawMode 
Specifies the new drawing mode. This parameter can be one of the following 
values: 


Return Value 


Comments 


See Also 


Value 


R2_BLACK 
R2_ WHITE 
R2_NOP 
R2_NOT 


-R2_COPYPEN 


R2_NOTCOPYPEN 
R2_MERGEPENNOT 


R2. MASKPENNOT 


R2_MERGENOTPEN 


-R2. MASKNOTPEN 


R2_MERGEPEN 
R2_NOTMERGEPEN 
R2_MASKPEN 
R2_NOTMASKPEN 


R2_XORPEN 


R2_NOTXORPEN 
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Meaning 


Pixel is always black. 

Pixel is always white. 

Pixel remains unchanged. 

Pixel is the inverse of the screen color. 
Pixel is.the pen color. 

Pixel is the inverse of the pen Solar 


Pixel is a combination of the pen color and the inverse of 
the screen color (final pixel = (~screen pixel) | pen). 
Pixel is a combination of the colors common to both the 


pen and the inverse of the screen (final pixel = (~screen 
pixel) & pen). 


Pixel is a combination of the screen color and the inverse 


of the pen color (final pixel = (~pen) | screen pixel). 
Pixel is a combination of the colors common to both the 
screen and the inverse of the pen (final eco (~pen) & 
screen pixel). 

Pixel is a combination of the pen color and the screen 
color (final pixel = pen | screen pixel). 

Pixel is the inverse of the R2- MERGEPEN color (final 
pixel = ~(pen | screen pixel)). 2 
Pixel is a combination of the colors common to both the 
pen and the screen (final pixel = pen & screen pixel). 
Pixel is the inverse of the R2_MASKPEN color (final 
pixel = ~(pen & screen pixel)). | 

Pixel is a combination of the colors that are in the 

pen and in the screen, but not in both (final pixel = 
pen “ screen pixel). 

Pixel is the inverse of the R2 _XORPEN color (final 
pixel = ~(pen * screen pixel)). 


The return value specifies the previous drawing mode, if the function is successful. 


_ The drawing mode is for raster devices only; it does not apply to vector devices. 


Drawing modes are binary raster-operation codes representing all possible 
Boolean combinations of two variables. These values are created by using the bi- | 
nary operations AND, OR, and XOR (exclusive OR) and the unary operation NOT. 


GetDeviceCaps, GetROP2 
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SetScrollPos 


int SetScrollPos(hwnd, fnBar, nPos, fRepaint) 


HWND hwnd; 
int fnBar; 

int nPos; 

~ BOOL fRepaint; 


Parameters 


Return Value 
| Comments 


See Also 


/* handle of window with scroll bar sy 
/* scroll bar flag ey} 
/* new position of scroll box sal 
/* redraw flag 7 ot 


The SetScrollPos function sets the position of a scroll box (thumb) and, if re- 
quested, redraws the scroll bar to reflect the new position of the scroll box. 


hwnd | 
Identifies the window whose scroll bar is to be set. 


jnBar | 
Specifies the scroll bar to be set. This parameter can be one of the following 
values: | | 


Value Meaning 

SB_CTL Sets the position of the scroll box in a scroll bar. In this case, the 
hwnd parameter must be the handle of a scroll bar. 

SB_HORZ Sets the position of the scroll box in a window’s horizontal scroll bar. 

SB_VERT Sets the position of the scroll box in a window’s vertical scroll bar. 


nPos , 

Specifies the new position of the scroll box. It must be within the scrolling 
range. 

fRepaint : 
Specifies whether the scroll bar should be repainted to reflect the new scroll 
box position. If this parameter is TRUE, the scroll bar is repainted. If it is 
FALSE, the scroll bar is not repainted. 


The return value is the previous position of the scroll box, if the function is - 


- successful. Otherwise, it is zero. 


Setting the fRepaint parameter to FALSE is useful whenever the scroll bar will be 
redrawn by a subsequent call to another function. 


| GetScrollPos, GetScrollRange, ScrollWindow, SetScrollRange 
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SetScrollRange [2x] 


void SetScrollRange(hwnd, fnBar, nMin, nMax, fRedraw) 


HWND hwnd; 
int {fnBar; 

int nMin; 

int nMax; 
BOOL fRedraw; 


Parameters 


Return Value 


Comments 


/* handle of window with scroll bar */ 
/* scroll bar flag */ 
/* minimum scrolling position i 
/* maximum scrolling position */ 
/* redraw flag st | 


The SetScrollRange function sets minimum and maximum position values for the — 


given scroll bar. It can also be used to hide or show standard scroll bars. © 


hwnd 
Identifies a | window or a scroll bar, depending on the value of fnBar. 


jfnBar | 
Specifies the scroll bar to be set. This parameter can be one of the following 
values: 


Value Meaning | 
SB_CTL Sets the range of a scroll bar. In this case, the hwnd parameter must 
be the handle of a scroll bar. 7 | 
SB_HORZ Sets the range of a window’s horizontal scroll bar. 
~ SB_VERT Sets the range of a window’s vertical scroll bar. 


nMin | 
Specifies the minimum scrolling position. 


nMax 
Specifies the maximum scrolling position. 


{Redraw 
Specifies whether the scroll bar should be edna to reflect the change. If this 
parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar I is 
not redrawn. | 7 


This function does not return a value. 


An application should not call this function to hide a scroll bar while processing a 
scroll-bar notification message. 


If the call to SetScrollRange immediately follows the call to the SetScrollPos 
function, the fRedraw parameter in SetScrollPos should be zero, to prevent the 
scroll bar from being drawn twice. 


The default range for a standard scroll bar is 0 through 100. The default range 
for a scroll bar control is empty (both the nMin and nMax values are zero). The 
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difference between the values specified by the nMin and nMax parameters must _ 
not be greater than 32,767. | 


See Also GetScrollPos, GetScrollRange, ScrollWindow, SetScrollPos 
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UINT SetSelectorBase(selector, dwBase) 
UINT selector; /* new selector * / 
DWORD dwBase; /* new base -) 


The SetSelectorBase function sets the base and limit of a selector. 


Parameters selector 
Specifies the selector value to modify. 


dwBase | 
Specifies the new base value. This value is the starting linear address that selec- 
tor will reference. 


Return Value The return value is the selector value, or zero if an error occurs. 


See Also GetSelectorBase, GetSelectorLimit, SetSelectorLimit 


SetSelectorLimit 5 he [3.1 | 


UINT SetSelectorLimit(selector, dwBase) 
UINT selector; /* new selector sy 
DWORD dwBase; _—/* current base i | 


The SetSelectorLimit function sets the limit of a selector. 


Parameters selector 
7 Specifies the selector to modify. 


dwBase | 
Specifies the new limit value for selector. For an 80286 processor, this value 
must be less than 0x 10000. 


Return Value The return value is always zero. 
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See Also GetSelectorBase, GetSelectorLimit, SetSelectorBase 


SetSoundNoise [2x | 


int SetSoundNoise(fnSource, nDuration) 
int fnSource; /* source of noise */ 
int nDuration; /* duration of noise a | 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about audio functions, see the Microsoft Windows Multi- 
media Programmer’s Reference. 


SetStretchBItMode Shoe [ 2x] 


int SetStretchBltMode(hdc, fnStretchMode) 
HDC hdc; /* handle of device context */ 
int fnStretchMode; /* bitmap-stretching mode sa 


The SetStretchBltMode function sets the bitmap-stretching mode. The bitmap- 
stretching mode defines how information is removed from bitmaps that are com- 
pressed by using the StretchBit function. 


Parameters hdc . 
_ Identifies the device context. 


JnStretchMode 
Specifies the new bitmap-stretching mode. This parameter can be one of the fol- 
~ lowing values: | | ae 


Value Meaning | 


STRETCH_ANDSCANS Uses the AND operator to combine eliminated 
lines with the remaining lines. This mode pre- 
serves black pixels at the expense of colored or 
white pixels. It is the default mode. 

STRETCH_DELETESCANS Deletes the eliminated lines. Information in the 

| : eliminated lines is not preserved. | 

STRETCH_ORSCANS Uses the OR operator to combine eliminated lines 
with the remaining lines. This mode preserves 
colored or white pixels at the expense of black 
pixels. 
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Return Value The return value is the previous stretching mode, if the function is successful. It 
can be STRETCH_ANDSCANS, STRETCH_DELETESCANS, or 
STRETCH_ORSCANS. 


Comments The STRETCH_ANDSCANS and STRETCH_ORSCANS modes are typically 

: used to preserve foreground pixels in monochrome bitmaps. The __ 
STRETCH_DELETESCANS mode is typically used to preserve color in color bit- 
maps. 


See Also GetStretchBitMode, StretchBlit, StretchDIBits 


SetSwapAreaSize [2x] 


LONG SetSwapAreaSize(cCodeParagraphs) 
UINT cCodeParagraphs; /* number of paragraphs for code = 


The SetSwapAreaSize function sets the amount of memory that an application 
uses for its code segments. | 


Parameters cCodeParagraphs | | 
7 Specifies the number of 16-byte paragraphs requested by the application for use 
as code segments. If this parameter is zero, the return value specifies the current 
size of the code-segment space. 


Return Value The return value is the amount of space available for the code segment, if the func- 
tion is successful. The low-order word specifies the number of paragraphs ob- 
tained for use as a code-segment space (or the current size if the cCodeParagraphs 
parameter is zero); the high-order word specifies the maximum size available. 


Comments _ If cCodeParagraphs specifies a size larger than is available, this function sets the 
size to the available amount. The maximum amount of memory available is one 
half the space remaining after Windows is loaded. 


Calling this function can improve an application’s performance by preventing Win- 
dows from swapping code segments to the hard disk. However, increasing the 
code-segment space reduces the amount of memory available for data objects and 
can reduce the performance of other applications. 


See Also ~ GetNumTasks, Global Alloc 
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SsetSysColors = [2x] 


void SetSysColors(cDspElements, lpnDspElements, lpdwRgbValues) 


int cDspElements; /* number of elements to change */ 
const int FAR* /[pnDspElements; /* address of array of elements sa 
const COLORREF FAR* IpdwRgbValues;_ _—si/* address of array of RGB values */ 


The SetSysColors function sets the system colors for one or more display ele- 
ments. Display elements are the various parts of a window and the Windows back- 
ground that appear on the screen. 7 


_ The SetSysColors function sends a WM_SYSCOLORCHANGE message to all | 
windows to inform them of the change in color. It also directs Windows to repaint 
the affected portions of all currently visible windows. 


Parameters cDspElements 
Specifies the number of display elements in the array pointed to by the 
lpnDspElements parameter. 


[pnDspElements 
Points to an array of integers that specify the display elements to be changed. 
For a list of possible display elements, see the following Comments section. 


IpdwRgbValues 
Points to an array of unsigned long integers that contains the new RGB (red- 
green-blue) color value for each display element in the array pointed to by the 
[pnDspElements parameter. | 


Return Value This function does not return a value. 


Comments ~The SetSysColors function changes the current Windows session only. The new 
colors are not saved when Windows terminates. 


Following are the display elements that may be used in the IpnDspElements array: 


Value | Meaning 

COLOR_ACTIVEBORDER | Active window border. 

COLOR_ACTIVECAPTION Active window title. 

COLOR_APPWORKSPACE Background color of multiple document: 
| | interface (MDI) applications. 

COLOR_BACKGROUND | Desktop. 

COLOR_BTNFACE Face shading on push buttons. 

COLOR_BTNHIGHLIGHT Selected button in a control. 

COLOR_BTNSHADOW Edge shading on push buttons. 


COLOR_BTNTEXT | Text on push buttons. 
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Value 


COLOR_CAPTIONTEXT 


COLOR_GRAYTEXT 


COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_INACTIVECAPTIONTEXT 
COLOR_MENU 
COLOR_MENUTEXT 
COLOR_SCROLLBAR 
COLOR_WINDOW 


~ COLOR_WINDOWFRAME 


Example 


See Also 


COLOR_WINDOWTEXT 


Meaning 
Text in title bar, size button, scroll-bar 
arrow button. 


Grayed (dimmed) text. This color is zero if 
the current display driver does not support a 
solid gray color. 


Background of selected item ina control. 
Text of selected item in a control. 
Inactive window border. 

Inactive window title. 

Color of text in an inactive title. 
Menu background. 
Text in menus. 

Scroll-bar gray area. 

Window background. 

Window frame. 

Text in windows. 


The following example changes the window background to black and the text in 


the window to green: 


int aiDspElements[2]; 
DWORD aRgbValues[2]; 


aiDspElements[@] = COLOR_WINDOW; 


aRgbValues[Q@] = 
0x00, 
0x00, 
0x00); 


RGB ( 

/* red * / 
/* green */ 
/* blue */ 


aiDspElements[1] = COLOR_WINDOWTEXT; 


aRgbValues[1l] = 
0x00, 
Oxff, 
Qx00); 


RGB ( 

/* red */ 
/* green */ 
/* blue */ 


SetSysColors(2, aiDspElements, aRgbValues); 


GetSysColor 
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SetSysModalWindow | oy 


HWND SetSysModalWindow(hwnd) 


HWND hwnd; _/* handle of window to become system modal | | 
The SetSysModal Window function makes the given window the system-modal 
window. 

Parameters § hwnd 


Identifies the window to be made system modal. 


ReturnValue = =‘ The return value is the handle of the window that was previously the system- 
modal window, if the function is successful. 


Comments If another window is made the active window (for example, the system-modal win- 
dow creates a dialog box that becomes the active window), the active window be- 
comes the system-modal window. When the original window becomes active 
again, it is once again the system-modal window. To end the system-modal state, 
destroy the system-modal window. 


If a WH_JOURNALRECORD hook is in place when SetSysModal Window i is 
called, the hook is called with a hook code of HC_SYSMODALON (for turning 
on the system-modal window) or HC SY SMODALOFE (for turning off the 
system-modal window). 


See Also GetSysModalWindow 


SetSystemPaletteUse = | 


UINT SetSystemPaletteUse(hdc, fuStatic) 3 
HDC hdc; /* handle of device context sy om 
UINT fuStatic; — is system-palette contents sa 


The SetSystemPaletteUse function sets the use of static colors in the system 

_ palette. The default system palette contains 20 static colors, which are not changed 
when an application realizes its logical palette. An application can use SetSystem- 
PaletteUse to change this to two static colors (black and Rae 


Parameters hdc nadas! eo | 
| | Identifies the device context. This device context must support color palettes. 
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Return Value 


Comments 


fuStatic 
Specifies the new use of the sei ne This parameter can be either of the 
following values: 


Value Meaning 

SYSPAL_NOSTATIC System palette contains no static colors except black and 
white. 

SYSPAL_STATIC System palette contains static colors that will not change 


when an application realizes its logical palette. 


The return value is the previous setting for the static colors in the system palette, 
if the function is successful. This setting is either SYSPAL_NOSTATIC or 
SYSPAL_STATIC. 


An application must call this function only when its window is maximized and has 
the input focus. 


If an application calls SetSystemPaletteUse with fuStatic set to 
SYSPAL_NOSTATIC, Windows continues to set aside two entries in 
the system palette for pure white and pure black, respectively. 


After calling this function with fuStatic set to SYSPAL_NOSTATIC, an applica- 
tion must follow these steps: 


1. Call the UnrealizeObject function to force the graphics device interface (GD) 
to remap the logical palette completely when it is realized. 


2. Realize the logical palette. 
3. Call the GetSysColor function to save the current system-color settings. 


4. Call the SetSysColors function to set the system colors to reasonable values 
using black and white. For example, adjacent or overlapping items (such as win- 
dow frames and borders) should be set to black and white, respectively. 


5. Send the WM_SYSCOLORCHANGE message to other top-level windows to 


allow them to be redrawn with the new system colors. 


When the application’s window loses focus or closes, the application must per- 
form the following steps: 


1. Call SetSystemPaletteUse with the ESIC parameter set to 
SYSPAL_STATIC. 


2. Call UnrealizeObject to torce GDI to remap the logical ee completely 
when it is realized. 


3. Realize the logical palette. | 
4. Restore the system colors to their previous values. 
5. Send the WM_SYSCOLORCHANGE message. 
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See Also GetSysColor, SetSysColors, SetSystemPaletteUse, UnrealizeObject 


SetTextAlign | rex | 


UINT SetTextAlign(hdc, fudlign) 
HDC hdc; /* handle of device context | 
UINT fuAlign; — _/* text-alignment flags ay | 


The SetTextAlign function sets the text-alignment flags for the given device con- 
text. | 


Parameters hdc 

Identifies the device context. 
fudlign 

Specifies text- valipnnient flags. The flags specify the relationship between a 
point and a rectangle that bounds the text. The point can be either the current 
position or coordinates specified by a text-output function (such as the Ext- 
TextOut function). The rectangle that bounds the text is defined by the adja- 
cent character cells in the text string. | 


The fuAlign parameter can be one or more flags from the following three cate- 
gories. Choose only one flag from each category. 


The first category affects text alignment in the x-direction: 


Value Meaning | 
TA_CENTER _ Aligns the point with the horizontal center of the bounding 
| rectangle. | 
TA_LEFT Aligns the point with the left side of the bounding rectangle. This 
| is the default setting. 
TA_RIGHT Aligns the point with the right side of the ponte sacthaiale: 


The second category affects text alignment in the s arecior 
Value Meaning 
TA_BASELINE Aligns the point with the base line of the chosen font. 


TA_BOTTOM Aligns the point with the bottom of the bounding rectangle. 


TA_TOP | Aligns the point with the top of the bounding cine This is 
| the default setting. 


The third category determines whether the current nt position 1S updated when text 
iS written: | , 
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Value 2 Meaning 


TA_NOUPDATECP Does not update the current position after each call to a 
text-output function. This is the default setting. 


TA_UPDATECP Updates the current x-position after each call to a text- 
output function. The new position is at the right side of the 
bounding rectangle for the text. When this flag is set, the 
coordinates specified in calls to the TextOut function are 


ignored. 
Return Value The return value is the previous text-alignment settings, if the function is success- 
ful. The low-order byte contains the horizontal setting; the high-order byte con- 
tains the vertical setting. Otherwise, the return value is zero. 
Comments The text-alignment flags set by SetTextAlign are used by the TextOut and Ext- 
TextOut functions. | 
Example The following example uses the GetTextF ace function to retrieve the name of the 
current typeface, calls SetTextAlign so that the current position is updated when 
the TextOut function is called, and then writes some introductory text and the 
name of the typeface by calling TextOut: 
int nFaceNameLen; 
char aFaceName[8@]; 
nFaceNameLen = GetTextFace(hdc, /* returns length of string */ 
sizeof(aFaceName), /* size of face-name buffer ef 
(LPSTR) aFaceName) ; /* address of face-name buffer */ 
SetTextAlign(hdc, | 
TA_UPDATECP) ; /* updates current position * / 
MoveTo(hdc, 100, 100); /* sets current position * / 
TextOut(hdc, 0, @, /* uses current position for text */ 
"This is the current face name: ", 31); 
TextOut(hdc, 0, 0, aFaceName, nFaceNameLen) ; 
See Also ExtTextOut, GetTextAlign, TextOut 


int SetTextCharacterExtra(hdc, nExtraSpace) 
HDC hdc; | /* handle of device context 


int nExtraSpace; /* extra character spacing ~ 


ol 
“] 
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The SetTextCharacterExtra function sets the amount of intercharacter spacing. 
The graphics device interface (GDI) adds this spacing to each character, including 
_ break characters, when it writes a line of text to the device context. 


Parameters hdc 
Identifies the device context. 


nExtraSpace 
Specifies the amount of extra space, in logical units, to be added to each charac- 
ter. If the current mapping mode is not MM_TEXT, this parameter is trans- 
formed and rounded to the nearest pixel. 


Return Value © The return value is the previous intercharacter spacing, if the function is successful. 
Comments The default value for the amount of intercharacter spacing is Zero. 
See Also GetTextCharacterExtra 


SetTextColor aie atteat bor [ax] 
COLORREF SetTextColor(hdc, clrref) 


HDC hdc; /* handle of device context  —*/ 
COLORREF clrref; /* new color for text */ 


The SetTextColor function sets the text color to the specified color. The system 
uses the text color when writing text to a device context and also when converting 
bitmaps between color and monochrome device contexts. 


Parameters hdc 
Identifies the device context. 


clrref 
Specifies the color of the text. 


— Return Value The return value is the RGB (red-green-blue) value for the previous text color, if 
the oceae is successful. 


Comments eee be the device cannot represent the specified color, the system sets oe text élor to 
| ~~ the nearest physical color. 


The okra color for a character is specified by the SetBkColor and SetBk- | 
Mode functions. 
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Example The following example sets the text color to red if the GetTextColor function de- 
- termines that the current text color is black. The text color is specified by using the 


RGB macro. 
DWORD dwColor; 


dwColor = GetTextColor(hdc); 
if (dwColor == RGB(@, Q, @)) /* if current color is black */ 
SetTextColor(hdc, RGB(255, @, @)); /* sets color to red */ 


See Also GetTextColor, BitBlt, SetBkColor, SetBkMode 


SetTextJustification — a 


int SetTextJustification(hdc, nExtraSpace, cBreakChars) 


HDC hdc; /* handle of device context : ay 
int nExtraSpace; /* space to add to string | 7 | 
int cBreakChars; /* number of break characters i in the string i 


The SetTextJustification function adds space to the break characters in a string. 
An application can use the GetTextMetrics function to retrieve a font’s break 


character. 


Parameters hdc 
Identifies the device context. 


nExtraSpace 
Specifies the total extra space, in logical units, to be added to the line of text. If 
the current mapping mode is not MM_TEXT, the value given by this parameter 
is converted to _ current mapping mode and rounded to the nearest device 


unit. 
cBreakChars 
Specifies the number of break characters in the line. 
Return Value The return value is 1 if the function is successful. Otherwise, it is zero. 
Comments After the SetText Justification function is called, a call to a text-output function 


(for examnle, TextQOnt) ai ctribuites the enecified extra cnaca avenly among tha 


specified number of break characters. The break character is usually the space 
character (ASCII 32), but it may be defined by a font as some other character. 


The GetTextExtent function is typically used with SetTextJustification. The 
~GetTextExtent function computes the width of a given line before alignment. An 


Example 


aPoints[@]. 
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application can determine how much space to specify in the nExtraSpace parame- 
ter by subtracting the value returned by GetTextExtent from the width of the 
string after alignment. 


The SetTextJustification function can be used to align a line that contains 
multiple runs in different fonts. In this case, the line must be created piecemeal by 
aligning and writing each run separately. 


Because rounding errors can occur during alignment, the system keeps a running 
error term that defines the current error. When aligning a line that contains 
multiple runs, GetTextExtent automatically uses this error term when it computes 
the extent of the next run, allowing the text-output function to blend the error into 
the new run. After each line has been aligned, this error term must be cleared to 
prevent it from being incorporated into the next line. The term can be cleared by 
calling SetText Justification with the nExtraSpace parameter set to zero. 


The following example writes two lines of text inside a box; one of the lines is 
aligned, and the other is not. The GetTextExtent function determines the width of © 
the unaligned string. The GetTextMetrics function determines the break character 
that is used by the current font; this information is then used to determine how 
many break characters the string contains. The SetText Justification function 
specifies the total amount of extra space and the number of break characters to dis- 
tribute it among. After writing a line of aligned text, SetTextJustification is called 
again, to set the error term to zero. | 


POINT aPoints[S]; 

int iLMargin = 10, iRMargin = 10, Hone ern, 

int cchString; : 

LPSTR IpszJustified = "Text to be justified in this test. ae 
DWORD dwExtent; | 

WORD wlextWidth; 

TEXTMETRIC tm; 


int j, cBreakChars; 


x = 100; aPoints[@].y = 50; 
aPoints[1].x = 600; aPoints[l].y = 50; 
aPoints[2].x = 600; aPoints[2].y = 200; 
aPoints{[3].x = 100; aPoints[3].y = 200; 
aPoints[4].x = 100; aPoints[4].y = 5@; 


Polyline(hdc, aPoints, sizeof(aPoints) / sizeof(POINT)): 


TextOut(hdc, 100 + iLMargin, 100, "Unjustified text.", 17); 


cchString = Istrlen(]lpszdustified); 
dwExtent = GetTextExtent(hdc, lpszJustified, cchString); 
wlextWidth = LOWORD(dwExtent); | 


— iBoxWidth = aPoints[1].x - aPoints[Q@].x; 


GetTextMetrics(hdc, &tm); 
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See Also 


SetTimer 


for (cBreakChars = @, j = 
if (*(lpszJustified + 
cBreakChars++; 


@; j < cchString; j++) 
j) == (char) tm.tmBreakChar) 


SetTextJustification(hdc, 
iBoxWidth - wlextWidth - (iLMargin + iRMargin), 
cBreakChars) ;. 

TextOut(hdc, 100 + iLMargin, 150, Ipszdustified, cchString); 


SetTextdustification(hdc, @, @); /* clears error term */ 


GetMapMode, GetTextExtent, GetTextMetrics, SetMapMode, TextOut 


UINT SetTimer(hwnd, idTimer, uTimeout, tmprc) 


HWND hwnd; /* handle of window for timer messages oy 

UINT idTimer; /* timer identifier */ 

UINT uTimeout; /* time-out duration */ 

TIMERPROC tmprc; /* instance address of timer procedure i 
The SetTimer function installs a system timer. A time-out value is specified, and 
every time a time-out occurs, the system posts a WM_TIMER message to the in- 
stalling application’s message queue or passes the message to an application- 
defined TimerProc callback function. 

Parameters hwnd 


Identifies the window to be associated with the timer. If the tmprc parameter is 
NULL, the window procedure associated with this window receives the 
WM_TIMER messages generated by the timer. If this parameter is NULL, no 
window is associated with the timer. 

idTimer 
Specifies a nonzero timer identifier. If the hwnd parameter is NULL, this pa- 
rameter is ignored. 


uTimeout 
Specifies the time-out value, in milliseconds. 


tm 
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tmprc 
Specifies the procedure-instance address of the callback function that processes 
the WM_TIMER messages. If this parameter is NULL, the WM_TIMER mes- 
sages are placed in the application’s message queue and the hwnd member of | 
the MSG structure contains the window handle specified in hwnd. For more in- 
formation, see the description of the TimerProc callback function. 


The MSG structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is the identifier of the new timer if hwnd is NULL and the func- 
| tion is successful. An application passes this value to the KillTimer function to 
kill the timer. The return value is nonzero if hwnd is a valid window handle and 
the function is successful. Otherwise, the return value is zero. 


Comments — Timers are a limited global resource; therefore, it is important that an application 
check the value returned by the SetTimer function to verify that a timer is avail- 
able. 


The tmprc parameter must specify a procedure-instance address of the callback 
function, and the callback function must be exported in the application’s module- 
definition file. A procedure-instance address can be created by using the Make- 
ProcInstance function. The callback function must use the Pascal calling 
convention and must be declared as FAR. 


Example The following example installs a system timer. The system will pass WM_TIMER 
messages generated by the timer to the “MyTimerProc” callback function. 7 


TIMERPROC 1pfnMyTimerProc; 


— IpfnMyTimerProc = (TIMERPROC) MakeProcInstance(MyTimerProc, hinst); 
SetTimer(hwnd, ID_MYTIMER, 5000, IpfnMyTimerProc) ; 


See Also - KillTimer, MakeProcInstance, TimerProc 
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SetViewportExt 


DWORD SetViewportExt(hdc, nXExtent, nYExtent) 


HDC hdc; 
int nXExtent; 
int nYExtent; 


Parameters 


Return Value 


Comments 


/* handle of device context */ 
/* x-extent of viewport sf | 
/* y-extent of viewport **/ 


The Set ViewportExt function sets the x- and y-extents of the viewport of the 
given device context. The viewport, along with the window, defines how points 
are converted from logical coordinates to device coordinates. 


hdc 
Identifies the device context. 


nXExtent | 
Specifies the x-extent, in device units, of the viewport. 


nYExtent 
Specifies the y-extent, in device units, of the viewport. 


The return value is the previous viewport extents, in device units, if the function is 
successful. The low-order word contains the previous x-extent; the high-order 
word contains the previous y-extent. Otherwise, the return value is zero. 


When the following mapping modes are set, calls to the SetWindowExt and 
Set ViewportExt functions are ignored: 


MM_HIENGLISH 
MM_HIMETRIC 
MM_LOENGLISH 
MM_LOMETRIC 
MM_TEXT 
MM_TWIPS 


When the mapping mode is MM_ISOTROPIC, an application must call the 
SetWindowExt function before calling Set ViewportExt. | 


The x- and y-extents of the viewport define how much the graphics device inter- 


face (GDI) must stretch or compress units in the logical coordinate system to fit 


units in the device coordinate system. For example, if the x-extent of the window © 
is 2 and the x-extent of the viewport is 4, GDI converts two logical units 


(measured from the x-axis) into four device units, Similarly, if the y-extent of the _ 
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window is 2 and the y-extent of the viewport is —1, GDI converts two logical units 


(measured from the y-axis) into one device unit. 


The extents also define the relative orientation of the x- and y-axes in both coordi- 


nate systems. If the signs of matching window and viewport extents are the same, 
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Example 


See Also 


the axes have the same orientation. If the signs are different, the orientation is 
reversed. For example, if the y-extent of the window is 2 and the y-extent of the 
viewport is —1, GDI converts the positive y-axis in the logical coordinate system 
to the negative y-axis in the device coordinate system. If the x-extents are 2 and 4, 
GDI converts the positive x-axis in the logical coordinate system to the positive 
X-axis in the device coordinate system. 


The following example uses the Set-MapMode, SetWindowExt, and Set- 
ViewportExt functions to create a client area that is 10 logical units wide and 10 
logical units high, and then draws a rectangle that is 4 logical units wide and 4 logi- 
cal units high: | 


HDC hdc; 
RECT rc; 


GetClientRect(hwnd, &rc); 

hdc = GetDC(hwnd); 

SetMapMode(hdc, MM_ANISOTROPIC); 
SetWindowExt(hdc, 10, 10); 
SetViewportExt(hdc, rc.right, rc.bottom); 
Rectangle(hdc, 3, 3, 7, 7); 

ReleaseDC( hwnd, hdc); 


Get ViewportExt, SetWindowExt 


SetViewportExtEx SP pee rai 


BOOL SetViewportExtEx(hdc, nX, nY, lpSize) 


HDC hdc; 

int nX3 

int nY; 4 
SIZE FAR®* [pSize; 


Parameters 


/* handle of device context aa 
/* x-extent of viewport 3 | 
/* y-extent of viewport sa 
/* address of struct. with prev. extents | 


The Set ViewportExtEx function sets the x- and y-extents of the viewport of the 
specified device context. The viewport, along with the window, defines how 
points are mapped from logical coordinates to device coordinates. 


hdc 
Identifies the device context. 


nxX 
Specifies the x-extent of the viewport, in device units. 


ny 
Specifies the y-extent of the viewport, in device units. 
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IpSize | 

Points to a SIZE structure. The previous extents of the viewport, in device 
units, are placed in this structure. If JpSize is N ULL, nothing is returned. The 
SIZE structure has the following form: 


typedef struct tagSIZE { 
int cx; 
int cy; 

} SIZE; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments When the following mapping modes are set, calls to the SetWindowExtEx and 
Set ViewportExtEx functions are ignored: 


MM_HIENGLISH 
MM_HIMETRIC 
MM_LOENGLISH 
MM_LOMETRIC 
MM_TEXT 
MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindow- 
ExtEx function before it calls Set ViewportExtEx. 


See Also . SetWindowExtEx 
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DWORD Set ViewportOrg(hdc, nXOrigin, ny Origin), 


HDC hdc; _ /* handle of device context 
int nXOrigin; /* x-coordinate of new origin ¥ 
‘int nYOrigin; /* y-coordinate of new origin ial 


~ The SetViewportOrg function sets the viewport origin of the specified device con- 
text. The viewport, along with the window, defines how points are converted from 
logical coordinates to device coordinates. 


Parameters hdc 
Identifies the device context. - 


Return Value 


Comments 


Example 


See Also 


SetViewportOrgEx 879 © 


nX Origin 
Specifies the x-coordinate, in device coordinates, of the origin of the viewport. 
This value must be within the range of the device coordinate system. 


nYOrigin 
Specifies the y-coordinate, in device coordinates, of the origin of the viewport. 
This value must be within the range of the device coordinate ee 


The return value is the coordinates of the previous viewport origin, in device units, 
if the function is successful. The low-order word contains the previous x-coordi- 


nate; the high- order word contains the previous ie “coordinate. Otherwise, the re- 


turn value is zero. 


The viewport origin is the origin of the device coordinate system. The graphics 


_ device interface (GDI) converts points from the logical coordinate system to 


device coordinates. (An application can specify the origin of the logical coordinate 
system by using the SetWindowOrg function.) GDI converts all points in the logi- 
cal coordinate system to device coordinates in the same way as it converts the 
origin. 


The following example uses the Set ViewportOrg function to set the viewport 
origin to the center of the client area and then draws a rectangle centered over the 
origin: 


HDC hdc; 


RECT rc; 


GetClientRect(hwnd, &rc); 

hdc = GetDC( hwnd); 

SetViewportOrg(hdc, rc.right/2, rc.bottom/2) ; 
Rectangle(hdc, -100, -100, 100, 100); 
ReleaseDC(hwnd, hdc); 


SetWindowOrg 


SetViewportOrgEx ed oe [8] 


BOOL SetViewportOrgEx(hdc, nX, nY, lpPoint) 


HDC hdc; 
int 1X; | 
int nY; 


/* handle of device context a 
/* x-coordinate of new origin _ a 
/* y-coordinate of new origin | **/ 


POINT FAR® [pPoint; /* address of struct. with prev. origin 7 | 
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The Set ViewportOrgEx function sets the viewport origin of the specified device 
context. The viewport, along with the window, defines how points are mapped 
from logical coordinates to device coordinates. 


Parameters hdc 
Identifies the device context. 


nxX 
Specifies the x-coordinate, in device units, of the origin of the viewport. 


nY | 
Specifies the y-coordinate, in device units, of the origin of the viewport. 


lpPoint 
Points to a POINT structure. The previous origin of the viewport, in device 
_ coordinates, is placed in this structure. If JpPoint is NULL, nothing is returned. 
The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also SetWindowOrgEx 


SetVoiceAccent - ‘Da 


int Set VoiceAccent(n Voice, nTempo, nVolume, fnMode, nPitch) 


int nVoice; /* voice queue | 
int nTempo; /* number of quarter notes per minute *] 
int nVolume; /* volume level _ ld 
int fnMode; /* how notes are to be played. v] 
int nPitch; /* pitch “/ 


“wre 


This function is obsoiete. Use the Microsoft Windows muitimedia audio functions 
instead. For information about these functions, see the M icrosoft Windows Multi-. 
media Programmer’s Reference. 3 7 
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setVoiceEnvelope [ex] 


int SetVoiceEnvelope(n Voice, nShape, nRepeat) 


int nVoice; /* voice queue sf 
int nShape; /* index into an OEM wave-shape table / 
int nRepeat; EL : Tepetition count sa 


This function is obsolete. Use the Microsoft Winiawe multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 
media Programmer’s Reference. 


setVoiceNote — _ 


int SetVoiceNote(voice, value, length, cdots) 


int voice; /* voice queue a 
int value; /* note */ 
int length; /* length of note | 
int cdots; /* duration of note */ 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows ME | 
media Programmer’s Reference. 
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int Set VoiceQueueSize(n Voice, chQueue) 
int nVoice; /* voice queue el 
int chQueue; _—/* size of queue */ 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows ee 
media Programmer’ s Reference. 
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SetVoiceSound — [ex | 


int Set VoiceSound(n Voice, dwF requency, nDuration) 


int nVoice; /* voice queue *] 
DWORD dwFrequency; /* frequency Bi 
int nDuration; /* duration of sound */ 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoy Windows Multi- 
media Programmer’s Reference. 


‘SetVoiceThreshold a] 


int Set VoiceThreshold(voice, cNotesThreshold) 
int voice; /* voice queue sa | 
int cNotesThreshold; /* threshold level */ 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 
media Programmer’s Reference. 


SetWinDebuginto oo aa] 


BOOL Set WinDebugInfo(/pwdi) 
const WINDEBUGINFO FAR® [pwdi; /* address of WINDEBUGINFO structure a 


The SetWinDebugInfo function sets current system-debugging information for 
the debugging version of the Windows 3.1 operating system. 


Parameters ss lpwdi 
Points to a WINDEBUGINFO structure that specifies the type of debugging in- 
formation to be set. The WINDEBUGINFO structure has the following form: 


typedef struct tagWINDEBUGINFO { 
UINT flags; 
DWORD dwOptions; 
DWORD dwFilter; 
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char achAllocModule[8]; 
DWORD = dwAllocBreak; 
~ DWORD  dwAllocCount; 
} WINDEBUGINFO; 


For a full description of this structure, see the M icrosoft Windows Program- 
_ mer’s Reference, Volume 3. 


~ Return Value The return value is nonzero if the function is successful. It is zero if the pointer 
specified in the Jpwdi parameter is invalid, the flags member of the WIN- 
DEBUGINFO structure is invalid, or the function is not called in the debugging 
version of Windows 3.1. 


Comments _ The flags member of the WINDEBUGINEO structure specifies which debugging 


information should be set. Applications need initialize only those members of the 
WINDEBUGINFO structure that correspond to the flags set in the flags member. 


Changes to debugging information made by calling SetWinDebugInfo apply only 
until you exit the system or restart your computer. 


See Also GetWinDebugInfo 


SetWindowExt | oe 


DWORD SetWindowExt(hdc, nXExtent, nYExtent) 


HDC hdc; /* handle of device context */ 
int nXExtent; /* x-extent of window ec | 
int nYExtent; /* y-extent of window / 


The SetWindowExt function sets the x- and y-extents of the window associated © 
with the given device context. The window, along with the viewport, defines how 
logical coordinates are converted to device coordinates. 


Parameters  —Ss_ hdc 
Identifies the device context. 


nX Extent 
Specifies the x-extent, in logical units, of the window. 


~nYExtent 
Specifies the y-extent, in logical units, of the window. 
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Return Value 


Comments 


The return value is the window’s previous extents, in logical units, if the function 
is successful. The low-order word contains the previous x-extent; the high-order 
word contains the previous y-extent. Otherwise, the return value is zero. 


When the following mapping modes are set, calls to the SetWindowExt and 
Set ViewportExt functions are ignored: 


-MM_HIENGLISH 


MM_HIMETRIC 
MM_LOENGLISH 
MM_LOMETRIC 
MM_TEXT 
MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindowExt 
function before calling SetViewportExt. 


The x- and y-extents of the window define how much the graphics device interface 
(GDI) must stretch or compress units in the logical coordinate system to fit units 


- in the device coordinate system. For example, if the x-extent of the window is 2 


Example 


and the x-extent of the viewport is 4, GDI converts two logical units (measured 
from the x-axis) into four device units. Similarly, if the y-extent of the window is 
2 and the y-extent of the viewport is —1, GDI converts two logical units (measured 
from the y-axis) into one device unit. 


The extents also define the relative orientation of the x- and y-axes in both coordi- 
nate systems. If the signs of matching window and viewport extents are the same, 
the axes have the same orientation. If the signs are different, the orientation is. 
reversed. For example, if the y-extent of the window is 2 and the y-extent of the 
viewport is —1, GDI converts the positive y-axis in the logical coordinate system 
to the negative y-axis in the device coordinate system. If the x-extents are 2 and 4, 
GDI converts the positive x-axis in the logical coordinate system to fo positive 
X-axis in the device coordinate system. 


The following example uses the SetCMapMode, Set WindowExt, and Set- 


_ ViewportExt functions to create a client area that is 10 logical units wide and 10 


logical units high and then draws a rectangle that is 4 units wide and 4 units high: 


HDC hdc: 


RECT rc; 


GetCiientrRect(fwnd, arc); 

hdc = GetDC(hwnd); | 

SetMapMode(hdc, MM_ANISOTROPIC); 
SetWindowExt(hdc, 10, 10); 
SetViewportExt(hdc, rc.right, rc.bottom); 
Rectangle(hdc, 3, 3, 7, 7); 

ReleaseDC( hwnd, hdc); 


- See Also 


SetWindowExtEx 
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GetWindowEXxt, Set ViewportExt 


BOOL SetWindowExtEx(hdc, nX, nY, lpSize) 


HDC hdc; 

int 1X3 

int nY; 

SIZE FAR® [pSize; 


Parameters 


Return Value — 


Comments 


IpSize 


/* handle of device context i 
/* x-extent of window | 
/* y-extent of window a | 
/* address of struct. with prev. extents +} 


The SetWindowExtEx function sets the x- and y-extents of the window as- 
sociated with the specified device context. The window, along with the viewport, 
defines how points are mapped from logical coordinates to device coordinates. 


hdc 
Identifies the device context. 


nX , 
Specifies the x-extent, in logical units, of the window. 


ny | 
Specifies the y-extent, in logical units,-of the window. 


Points to a SIZE structure. The previous extents of the window (in logical 
units) are placed in this structure. If IpSize is NULL nothing is returned. The 
SIZE structure has the following form: | 


typedef struct tagSIZE { 
int cx; 
int cy; 

} SIZE; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. z | 


~. The return value is nonzero if the function is successful. Otherwise, it is zero. 


| When the following mapping modes are set, calls to the SetWindowExtEx and 


Set ViewportExt functions are ignored: 


MM_HIENGLISH 
MM_HIMETRIC 
MM_LOENGLISH 
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MM_LOMETRIC 
MM_TEXT 
MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindow- 
ExtEx function before calling Set ViewportExt. 


See Also Set ViewportEXtEx 


SetWindowLong [ex] 


LONG SetWindowLong(hwnd, nOffset, nVal) 
HWND hwnd; /* handle of window * 
int nOffsets /* offset of value to set */ 
LONG nVal; /* new value */ 


The SetWindowLong function places a long value at the specified offset into the 
extra window memory of the given window. Extra window memory is reserved by 
specifying a nonzero value in the cbWndExtra member of the WNDCLASS- 
structure used with the RegisterClass function. 


Parameters hwnd 
Identifies the window. 


nOffset 
Specifies the zero-based byte offset of the value to change. Valid values are in 
the range zero through the number of bytes of extra window memory, minus 
four (for example, if 12 or more bytes of extra memory were specified, a value 
of 8 would be an index to the third long integer), or one of the ror owane values: 


Value Meaning 
GWL_EXSTYLE Extended window style 
GWL_STYLE Window style 


GWL_WNDPROC Long pointer to the window procedure 


The following values are also available when the hwnd parameter identifies a 


dialog hox: | 
Value Meaning 
DWL_DLGPROC Specifies the address of the dialog box procedure. 


DWL_MSGRESULT Specifies the return value of a message processed in the 
a dialog box Pocene: 


Return Value 


Comments 


Example 
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Value Meaning 


DWL_USER Specifies extra information that is private to the applica- 
tion, such as handles or pointers. 


nVal | 
Specifies the long value to place in the window’s reserved memory. 


The return value is the previous value of the specified long integer, if the function 
is successful. Otherwise, it is zero. 


If the SetWindowLong function and the GWL_WNDPROC index are used to set 
a new window procedure, that procedure must have the window-procedure form 
and be exported in the module-definition file of the application. For more informa- 
tion, see the description of the RegisterClass function. 


Calling SetWindowLong with the GCL_WNDPROC index creates a subclass of 
the window class used to create the window. An application should not attempt to 
create a window subclass for standard Windows controls such as combo boxes and 
buttons. 


An application should not use this function to set the WS_DISABLE style for a_ 
window. Instead, the application should use the EnableWindow function. 


To access any extra 4-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the nOffset parameter, © 
starting at O for the first 4-byte value in the extra space, 4 for the next 4- ie | 
value, and so on. 


An application can use the DWL_MSGRESULT value to return values from a 


dialog box procedure’s window procedure. Typically, a dialog box procedure must 


return TRUE in order for a value to be returned to the sender of the message. 
Some messages, however, return a value in the Boolean return value of the dialog 
box procedure. The following messages return values in the return value of the 
dialog box procedure: 


WM_CHARTOITEM 
WM_COMPAREITEM 
WM_CTLCOLOR 
WM_INITDIALOG | 
WM_QUERYDRAGICON 
WM_VKEYTOITEM 


The following example shows how to use the Set WindowLong function with the 


_ DWL_MSGRESULT value to return a value from a dialog box procedure. Appli- 
cations often include a switch statement to handle the messages that return values 
in the Boolean return value of the dialog box procedure, even when the dialog box 
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procedure does not process these messages. This practice makes it easy to revise 
the dialog box procedure to handle the message and has a negligible effect on 
speed and memory. 


BOOL CALLBACK MyDlgProc(hwndDlg, msg, wParam, 1Param) 
HWND hwndDlg; 
UINT msg; 
WPARAM wParam; 
LPARAM 1Param; 
{ 
BOOL fProcessed = FALSE; . 
LRESULT 1Result; 


/* 

* To return a value for a specific message, set 1Result to the 
* return value and fProcessed to TRUE. 

* / 


switch (msg) { 


/* process messages */ 


case WM_QUERYENDSESSION: 


/* | 

* Example: Do not allow the system to terminate 
* while the dialog box is displayed. 

* / 


fProcessed = TRUE; 
TResult = (LRESULT) (UINT) FALSE; 
break; 


default: 
break; 
} 


if (fProcessed) { 
switch (msg) { 
case WM_CTLCOLOR: 
case WM_COMPAREITEM: 
case WM_VKEYTOITEM: 
case WM _CHARTOITEM: 
case WM _QUERYDRAGICON: 
case WM_INIIDIALOG: 
return (BOOL) LOWORD(1Result); 
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default: 


SetWindowLong(hwndDlg, DWL_MSGRESULT, (LPARAM) 1]Result); 
'; 
} 
return fProcessed; 
} 
See Also EnableWindow, GetWindowLong, RegisterClass, Set WindowWord 


‘SetWindowOrg | - | a] 


DWORD SetWindowOrg(hdc, nXOrigin, nYOrigin) 


HDC hdc; /* handle of device context | 4 
int nXOrigin; /* x-coordinate to map to upper-left window corner a) 
int nYOrigin; /* y-coordinate to map to upper-left window corner | 


The SetWindowOrg function sets the window origin for the given device context. 


Parameters hdc | 
Identifies the device context. 


nX Origin 
Specifies the logical x-coordinate to emap to the upper-left corner of the window. 


nYOrigin 
Specifies the logical y-coordinate to map to the upper-left corner of the window. 


Return Value The return value is the coordinates of the previous window origin, in iecalt sits 
| if the function is successful. The low-order word contains the x-coordinate of the 
previous window origin; the high-order word contains s the y-coordinate. Other- 
wise, the return value is zero. 


Comments The window origin is the origin of the logical coordinate system for a window. 
By changing the window origin, an application can change the way the graphics 
device interface (GDI) converts logical coordinates to device coordinates (the 
: viewport). GDI converts logical coordinates to the device coordinates of the view- 
port in the same way as it converts the origin. 3 


To convert points to the right, an application can specify a negative value for the 
nX Origin parameter. Similarly, to convert points down (in the MM_TEXT map- 
ping mode), the nYOrigin parameter can be negative. _ 


Example | The following example uses the CopyMetaFile function to copy a metafile to a 
specified file, plays the copied metafile, uses the GetMetaFile function to retrieve 
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a handle of the copied metafile, uses the SetWindowOrg function to change the 
position at which the metafile is played 200 logical units to the as and then 
plays the metafile at the new location: 


HANDLE hmf, hmfSource, hmf0Old; 
LPSTR IpszFilel = "MFTest"; 


hmf = CopyMetaFile(hmfSource, lpszFilel); 
PlayMetaFile(hdc, hmf); 
DeleteMetaFile(hmf); 

hmfOld = GetMetaFile(lpszFilel); 
SetWindowOrg(hdc, -200, 0); 
PlayMetaFile(hdc, hmf0Old); 


DeleteMetaFile(hmfSource); 
DeleteMetaFile(hmf0l1d); 


See Also CopyMetaFile, GetMetaFile, GetWindowOrg, PlayMetaFile, Set ViewportOrg 
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BOOL SetWindowOrgEx (hdc, nX, nY, [pPoint) — 


HDC hdc; /* handle of device context */ 
int nX; /* x-coordinate of window */ 
int nY; /* y-coordinate of window ai 
POINT FAR* [pPoint; /* address of struct. with prev. origin ss */ 


The SetWindowOrgEx function sets the Sindow origin of the specified device 
context. The window, along with the viewport, defines how points are mapped 
from logical coordinates to device coordinates. 


Parameters hdc | 
Identifies the device context. 


nx . 
_ Specifies the logical x-coordinate of the new origin of the window. 


nY | | 
Specifies the logical y-coordinate of the new origin of the window. 

lpPoint 
Points to a POINT structure. The previous origin of the window is placed in 
this structure. If IpPoint is NULL nothing is returned. The POINT structure has 
the following form: 
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typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also” Set ViewportOrgEx 
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BOOL SetWindowPlacement(hwnd, lpwndpl) 
HWND hwnd; /* handle of the window | **/ 
const WINDOWPLACEMENT FAR® [pwndp!l; /* address of structure with position data a | 


The SetWindowPlacement function sets the show state and the normal restored) 
minimized, and maximized positions for a window. | 


Parameters hwnd 
Identifies the window. - 


lpwndpl 
Points to a WINDOWPLACEMEN T structure that specifies the new show 
_ state and positions. Tle WINDOWPLACEMENT structure has the following 


form: 


typedef struct tagWINDOWPLACEMENT { /* wndpl */ 
UINT length; | 
UINT flags; 
UINT showCmd; 
POINT ptMinPosition; 
POINT ptMaxPosition; 
RECT rcNormalPosition; 
} WINDOWPLACEMENT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value - The return value is nonzero if the function is successful. Otherwise, it is zero. 


See Also — GetWindowPlacement 
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SetWindowPos 


BOOL SetWindowPos(hwnd, hwndInsertAfter, X, ys, CX, CYs fuF lags) 
| 


HWND hwnd; /* handle of window 

HWND hwndInsertAfter; /* placement-order handle y, 

int x; /* horizontal position a | 

int y; /* vertical position 6 | 

int cx; /* width */ 

int cy; /* height oF 

UINT fuFlags; /* window-positioning flags =} 
The SetWindowPos function changes the size, position, and Z-order of child, pop- 
up, and top-level windows. These windows are ordered according to their appear- 
ance on the screen; the window on top receives the highest rank and is the first 
window in the Z-order. 

Parameters hwnd 


Identifies the window to be positioned. 


hwndInsertAfter 


Identifies the window to precede the positioned window in the Z-order. This pa- 
rameter must be a window handle or one of the following values: 


Value 


HWND_BOTTOM 


HWND_TOP 
HWND_TOPMOST 


HWND_NOTOPMOST 


Meaning 


Places the window at the bottom of the Z-order. If 
hwnd identifies a topmost window, the window loses 
its topmost status; the system places the window at the 
bottom of all other windows. 


Places the window at the top of the Z-order. 


Places the window above all non-topmost windows. 
The window maintains its topmost position even when 
it is deactivated. 


Repositions the window to the top of all non-topmost 
windows (that is, behind all topmost windows). This 
flag has no effect if the window is already a non- 
topmost window. 


For rules about how this parameter is used, see the following Comments section. 


Specifies the new position of the left side of the window. 


Specifies the new position of the top of the window. 


CX 


Specifies the new width of the window. 


Return Value 


Comments 
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cx 
Specifies the new width of the window. 

cy 
Specifies the new height of the window. 

 fuF lags | 
Specifies the window sizing and positioning options. This parameter c can be a 
combination of the following values: 


Value Meaning 


SWP_DRAWFRAME Draws a frame (defined in the window’s class descrip- 
tion) around the window. ar 


~SWP_HIDEWINDOW Hides the window. 
SWP_NOACTIVATE Does not activate the window. If this flag is not set, the 
window is activated and moved to the top of either the 


topmost or non-topmost group (depending on the set- 
ting of the hwndInsertAfter parameter). 


SWP_NOMOVE) | Retains the current position (ignores the x and y pa- 
rameters). 

SWP_NOSIZE ~ Retains the current size (ignores the cx and cy parame- 
ters). 

SWP_NOREDRAW Does not redraw changes. If this flag is set, no repaint- 


ing of any kind occurs. This applies to the client area, 
the non-client area (including the title and scroll bars), 
and any part of the parent window uncovered as a re- 

sult of the moved window. When this flag is set, the ap- 
plication must explicitly invalidate or redraw any parts 
of the window and parent window that must be 
redrawn. | 

SWP_NOZORDER Retains the current ordering (ignores the hwnd- 
InsertAfter parameter). 


SWP_SHOWWINDOW Displays the window. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


If the SWP_SHOWWINDOW or the SWP__ HIDEWINDOW flags ai are set, the win- 
dow cannot be moved or sized. 


All coordinates for child windows are client coordinates (relative to the epee ich 


corner of the parent window’s client area). 


A window can be made a topmost window either by setting the hwndInsertAfter 
parameter to HWND_TOPMOST and ensuring that the SWP_NOZORDER flag is 
not set, or by setting a window’s Z-order so that it is above any existing topmost 


windows. When a non-topmost window is made topmost, its owned windows are 


also made topmost. Its owners are not changed. 
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If neither SWP_NOACTIVATE nor SWP_NOZORDER is specified (that is, 
when the application requests that a window be simultaneously activated and 
placed in the specified Z-order), the value specified in hwndInsertAfter is used 
only in the following circumstances: 


=" Neither HWND_TOPMOST or HWND _NOTOPMOST: is specified in the 
hwndInsertAfter parameter. 


= The window specified in the hwnd parameter is not the active window. 


An application cannot activate an inactive window without also bringing it to the 
top of the Z-order. Applications can change the Z-order of an activated window 
without restrictions or activate a window and then move it to the top of the top- 
most or non-topmost windows. 


A topmost window is no longer topmost if it is repositioned to the bottom 
(HWND_BOTTOM) of the Z-order or after any non-topmost window. When a 
topmost window is made non-topmost, all of its owners and its owned windows 
are also made non-topmost windows. 


A non-topmost window may own a topmost window, but not vice versa. Any win- 
dow (for example, a dialog box) owned by a topmost window is itself made a top- 
most window, to ensure that all owned windows stay above their owner. 


Example The following example sets the size of a window equal to one-fourth the size of 
the desktop and then positions the window in the upper-left corner of the desktop: 


RECT rect; 
GetWindowRect(GetDesktopWindow(), &rect); 
SetWindowPos(hwnd, (HWND) NULL, @, @, 


rect.right / 2, rect.bottom / 2, 
SWP_NOZORDER | SWP_NOACTIVATE) ; 


See Also _ BringWindowToTop, GetWindowRect, MoveWindow 
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OR Set v 1L1UO WSLLOOK UL OOK, fikpi a) 
int idHook; /* type of hook to install | a 
HOOKPROC hkprc; _/* filter function procedure-instance address of 


The SetWindowsHook function is obsolete but has been retained for backward 
compatibility with Windows versions 3.0 and earlier. Applications written for Win- 
dows version 3.1 should use the SetWindowsHookEx function. 


Parameters 


idHook 


SetWindowsHook 
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The SetWindowsHook function installs an application-defined hook function into 
a hook chain. , 


Specifies the type of hook to be installed. This parameter can be c one of the fol- 


lowing values: 
Value 


WH_CALLWNDPROC 


WH_CBT 


WH_DEBUG 


WH_GETMESSAGE 


WH_HARDWARE 


WH_JOURNALPLAYBACK 


WH_JOURNALRECORD 


WH_KEYBOARD 


WH_MOUSE 


WH_MSGFILTER 


- WH_SHELL 


WH_SYSMSGFILTER 


Meaning 


Installs a window-procedure filter. For more in- | 
formation, see the description of the CallWnd- 
Proc callback function. 


Installs a computer-based training (CBT) filter. 
For more information, see the description of the 
CBTProc callback function. 


Installs a debugging filter. For more information, 
see the description of the DebugProc callback 
function. 


Installs a message filter. For more information, 


see the description of the GetMsgProc callback 


function. 
Installs a nonstandard hardware-message filter. 


_ For more information, see the description of the 


HardwareProc callback function. 

Installs a journaling playback filter. For more in- 
formation, see the description of the Journal- 
PlaybackProc callback function. | 


Installs a journaling record filter. For more infor- | 


mation, see the description of the Journal- 
RecordProc callback function. 


Installs a keyboard filter. For more information, 
see the description of the KeyboardProc call- 
back function. 


Installs a mouse-message filter. For more infor- 
mation, see the description of the MouseProc 
callback function. 


Installs a message filter. For more information, 
see the description of the aie ca callback 
function. | 


~ Installs a shell-application filter. For more infor- 
- mation, see the description of the pnenEres call- 


back function. | 

Installs a system-wide message filter. For more 
information, see the description of the SysMsg- 
Proc callback function. 
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Return Value 


Comments — 


hkpre 
Specifies the procedure-instance address of the application-defined hook proce- 
dure to be installed. 


The return value is a handle of the installed hook, if the function is successful. 
Otherwise, it is NULL. 


Before terminating, an application must call the UnhookWindowsHook function 
to free system resources associated with the hook. 


The WH_CALLWNDPROC hook affects system performance. It is supplied for 
debugging purposes only. 


The system hooks are a shared resource. Installing a hook affects all applications. 
Most hook functions must be in libraries. The only exception is 


~WH_MSGFILTER, which is task-specific. System hooks should be restricted to 


See Also 


SetWindowsHookEx 


special-purpose applications or to use as a development aid during debugging of 
an application. Libraries that no longer need the hook should remove the filter 
function. 


To install a filter function, the SetWindowsHook function must receive a proce- 
dure-instance address of the function and the function must be exported in the 
library’s module-definition file. A task must use the MakeProclInstance function 
to get a procedure-instance address. A dynamic-link library can pass the procedure 
address directly. 


DefHookProc, GetProcAddress, MakeProcInstance, MessageBox, 
PeekMessage, PostMessage, Renesas SetWindowsHookEx, 
Unhook WindowsHook 


HHOOK SetWindowsHookEx(idHook, hkprc, hinst, htask) 


int idHook; 
HOOKPROC hkprc; 
HINSTANCE hinst; 
HTASK htask: 


/* type of hook to install 7} 
/* procedure-instance address of filter function | **/ 
/* handle of application instance */ 


/* task to install the hook for */ 


The Set WindowsHookEx function installs an application-defined hook function 
into a hook chain. This function is an extended version of the SetWindowsHook 
function. : 


idHook 
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Specifies the type of hook to be installed. This parameter can be one of the fol- 


lowing values: 
Value 


WH_CALLWNDPROC 
WH_CBT 

WH_DEBUG 
WH_GETMESSAGE 
WH_HARDWARE 
-WH_JOURNALPLAYBACK 
WH_JOURNALRECORD 
WH_KEYBOARD 
WH_MOUSE 
WH_MSGFILTER 


WH_SYSMSGFILTER 


hkpre 


Meaning 


Installs a window-procedure filter. For more in- 
formation, see the description of the CallWnd- 
Proc callback function. 


Installs a computer-based training (CBT) filter. 
For more information, see the description of the 
CBTProc callback function. 


Installs a debugging filter. For more information, 
see the description of the DebugProc callback 
function. 


Installs a message filter. For more information, 
see the description of the GetMsgProc callback 
function. 


Installs a nonstandard hardware-message filter. — 
For more information, see the description of the 
HardwareProc callback function. 


Installs a journaling playback filter. For more in- 
formation, see the description of the Journal- 
PlaybackProc callback function. 


Installs a journaling record filter. For more infor- 
mation, see the description of the Journal- 
RecordProc callback function. 


Installs a keyboard filter. For more information, 
see the description of the KeyboardProc call- 
back function. 


Installs a mouse-message filter. For more infor- 
mation, see the description of the MouseProc 
callback function. 


Installs a message filter. For more information, 

see the description of the MessageProc callback _ 
function. | | 

Installs a system-wide message filter. For more 
information, see the description of the SysMsg- 
Proc callback function. 


_ Specifies the procedure-instance sete of the application- defined hook proce- 


dure to be installed. 


hinst 


Identifies the instance of the module containing the hook function. 
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Return Value 


Comments 


htask | 
Identifies the task for which the hook is to be installed. If this parameter is 
NULL, the installed hook function has system scope and may be called in the 
context of any process or task in the system. 


The return value is a handle of the installed hook, if the function is successful. The 
application or library must use this handle to identify the hook when it calls the 
CallNextHookEx and Unhook WindowsHookEx functions. The return value is 
NULL if an error occurs. 


An application or library can use the GetCurrentTask or GetWindowTask func- 
tion to obtain task handles for use in hooking a particular task. 


Hook procedures used with SetWindowsHookEx must be declared as follows: 


DWORD CALLBACK HookProc(code, wParam, 1Param) 
int code; 
WPARAM wParam; 
LPARAM 1Param; 
{ 
1 ae Oe, 
return Cal lNextHookEx(hhook, code, wParam, |1Param); 
} | 


Chaining to the next hook procedure (that is, calling the CallNextHookProc func- 
tion) is optional. An application or library can call the next hook procedure either 
before or after any processing in its own hook procedure. 


Before terminating, an application must call the Unhook WindowsHookEx func- 
tion to free system resources associated with the hook. . 


Some hooks may be set with system scope only, and others may be set only tor a 
specific task, as shown in the following list: 


Hook 


WH_CALLWNDPROC 
WH_CBT 

WH_DEBUG | 
WH_GETMESSAGE 
WH_HARDWARE 
WH_IOURNALRECORD 
WH_JOURNALPLAYBACK 
WH_KEYBOARD 
WH_MOUSE 
WH_MSGFILTER 


Scope 


Task or system 
Task or system 
Task or system 
Task or system 
Task or system 


System anlyv 


Lew see Nene 


System only 

Task or system 
Task or system 
Task or system 
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Hook Scope 
WH_SYSMSGFILTER System only 


For a given hook type, task hooks are called first, then system hooks. 


The WH_CALLWNDPROC hook affects system performance. It is supplied for 
debugging purposes only. 


The system hooks are a shared resource. Installing one affects all applications. All 
system hook functions must be in libraries. System hooks should be restricted to 
special-purpose applications or to use as a development aid during debugging of 
an application. Libraries that no longer need the hook should remove the filter 
function. 


_ Itis a good idea for several reasons to use task hooks rather than system hooks: 
They do not incur a system-wide overhead in applications that are not affected by _ 
the call (or that ignore the call); they do not require packaging the hook-procedure 
implementation in a separate dynamic-link library; they will continue to work 
even when future versions of Windows prevent applications from installing 
system-wide hooks for security reasons. 


To install a filter function, the SetWindowsHookEx function must receive a pro- 
cedure-instance address of the function and the function must be exported in the 
library’s module-definition file. Libraries can pass the procedure address directly. 
Tasks must use the MakeProcInstance function to get a procedure-instance 
address. Dynamic-link libraries must use the GetProcAddress function to geta 
procedure-instance address. | 


For a given hook type, task hooks are called first, then system hooks. 


The WH_. SYSMSGFILTER hooks are called before the WH _MSGFILTER 
hooks. If any of the WH_SYSMSGFILTER hook functions return TRUE, the 
WH_MSGFILTER hooks are not called. 


See Also . ~ CallNextHookEx, GetProcAddress MakeProclInstance, MessageBox, | 
| _ PeekMessage, PostMessage, SendMessage, Unhook WindowsHookEx 


SetWindowText et ee [eae] 
void SetWindowText(hwnd, Ipsz) 


HWND hwnd; /* handle of window */ 
LPCSTR Ipsz;__—_—s—/* address of string Ff. 
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Parameters 


| Return Value 


Comments 


Example 


See Also 


setWindowWord 


The SetWindowText function sets the given window’ title to the specified text. 
hwnd | 

Identifies the window or control whose text is to be set. 
Ipsz 

Points to a null-terminated string to be used as the new title or control text. 


This function does not return a value. 


This function causes a WM_SETTEXT message to be sent to the given window or 
control. 


If the window specified by the hwnd parameter is a control, the text within 
the control is set. If the specified window is a list-box control created with 
WS_CAPTION style, however, SetWindowText will set the caption for the 
control, not for the list-box entries. | 


The following example sets a window title: 


char szBuf[64]; 
char szFileName[64]; 


wsprintf((LPSTR) szBuf, "PrntFile - %s", (LPSTR) szFileName); 
SetWindowText(hwnd, (LPSTR) szBuf); 


GetWindowText 


WORD Set WindowWord(hwnd, nOffset, nVal) 


HWND hwnd; 


int nOffsets 


WORD nVal; 


Parameters 


/* handle of window | */ 
/* offset of value to set **/ 
/* new value */ 


The SetWindowWord function places a word value at the specified offset into the 


extra window memory of the given window. Extra window memory is reserved by 
anifrina NA NAN TFANMNr walia i in tha cehWndbivtro mambhar of the WNDCTL A Ss 


Speciy ALLS UW LEWVAIAWYIY Yuu IAd ULI UA BREUASBACROUR CE BERWEREA WE 


structure used with the RegisterClass function. 


hwnd 
Identifies the window. 


Return Value 


Comments 


See Also | 
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nOffset | 

Specifies the zero-based byte offset of the value to anne: Valid values are in 
the range zero through the number of bytes of extra window memory, minus 
two (for example, if 10 or more bytes of extra memory were specified, a value 
of 8 would be an index to the fifth integer), or one of the following values: 


Value — Meaning | 
GWW_HINSTANCE Specifies the instance handle of the module that owns the 
| window. 
GWW_ID Specifies the identifier of the child window. 
nVal 


Specifies the word value to be placed 1 in the endow: S a memory. 


The return value is the edits value of the specified word, if the function is 
successful. Otherwise, it is zero. 


To access any extra 2-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the nOffset parameter, 
starting at O for the first 2-byte value in the extra space, 2 for the next 2-byte 
value, and so on. 


An application should call the SetParent function, not the SetWindowWord func- 


_ tion, to change a value in the parent of a child window. 


~ GetWindowWord, RegisterClass, SetParent, SetWindowLong 


ShellExecute = 


#include <shellapi.h> 
HINSTANCE ShellExecute(hwnd, lpszOp, IpszFile, lpszParams, lpszDir, fsShowCmd) 


HWND hwnd; /* handle of parent window — 
LPCSTR IpszOp;_ /* address of string for operation to perform 
LPCSTR [pszFile; _/* address of string for filename st 
~ LPCSTR IpszParams; /* address of string for executable-file parameters */ 
~LPCSTR [pszDir; /* address of string for default directory | | | 
_/* whether file is shown when opened — | ee, 


int fsShowCmd; 


The ShellExecute function opens or prints the specified file. 
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Parameters 


hwnd | 
Identifies the parent window. This window receives any message boxes an ap- 
plication produces (for example, for error reporting). 


lpszOp 
Points to a null-terminated string specifying the operation to perform. This 
string can be “open” or “print”. If this parameter is NULL, “open” is the default 
value. 


lpszFile 
Points to a null-terminated etag specifying the file to open. 


[pszParams 
Points to a null-terminated string specifying parameters passed to the applica- 
tion when the /pszFile parameter specifies an executable file. If IpszFile points 
to a string specifying a document file, this parameter is NULL. 


[pszDir 
Points to a null- ected string sestinine the default directory. 


fsShowCmd 
Specifies whether the soplicadon window is to be shown when the application 
is opened. This parameter can be one of the following values: 


Value Meaning 
SW_HIDE | Hides the window and passes activation to 
| another window. 
SW_MINIMIZE Minimizes the specified window and activates the 
top-level window in the system’s list. 
SW_RESTORE Activates and displays a window. If the window 


is minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_SHOWNORMAL). 


SW_SHOW Activates a window and displays it in its current 
7 size and position. 
SW_SHOWMAXIMIZED Activates a window and displays it as a maxi- 
mized window. 
SW_SHOWMINIMIZED Activates a window and displays it as an icon. 


SW_SHOWMINNOACTIVE Displays a window as an icon. The window that is 
currently active remains active. 


SW_SHOWNA Displays a window in its current state. The win- 
dow that is currently active remains active. 


SW SHOWNOACTIVATE Displays a window in its most recent size and 
| position. The window that is currently active re- 
mains active. 


Return Value 


Errors 


Comments — 


Value 
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Meaning 


SW_SHOWNORMAL Activates and displays a window. If the window 


is minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_RESTORE). 


The return value is the instance handle of the application that was opened or 
printed, if the function is successful. (This handle could also be the handle of a 
DDE server application.) A return value less than or equal to 32 specifies an error. 
The possible error values are listed in the following Comments section. 


The ShellExecute function returns the value 31 if there is no association for the 
specified file type or if there is no association for the specified action within the 
file type. The other possible error values are as follows: , | 


Value 


0 


21 


Meaning 

System was out of memory, executable file was corrupt, or relocations were 
invalid. 

File was not found. 

Path was not found. 

Attempt was made to dynamically link to a task, or there was a sharing or 


~ network-protection error. 


Library required separate data segments for each task. 
There was insufficient memory to start the application. 
Windows version was incorrect. 


Executable file was invalid. Either it was not a Windows application or 
there was an error in the .EXE image. 


Application was designed for a different operating system. 
Application was designed for MS-DOS 4.0. 
Type of executable file was unknown. 


Attempt was made to load a real-mode application (developed for an earlier 
version of Windows). 


Attempt was made to load a second instance of an executable file contain- 
ing multiple data segments that were not marked read-only. 


Attempt was made to load a compressed executable file. The file must be. 
decompressed before it can be loaded. | 


Dynamic- -link library (DLL) file was invalid. One of the DLLs required to 


_ run this application was corrupt. 


Application requires Microsoft Windows 32-bit extensions. 


The file specified by the [pszFile parameter can be a document file or an execu- 


table file. If it is a document file, this function opens or prints it, depending on the 
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value of the /pszOp parameter. If it is an executable file, this function opens it, | 
even if the string “print” is pointed to by /pszOp. 


See Also FindExecutable 


ShellProc 


LRESULT CALLBACK ShellProc(code, wParam, lParam) 


int code; /* process-message flag sa | 
WPARAM wParam; /* current-task flag sal 
LPARAM /Param; /* undefined sa | 


The ShellProc function is a library-defined callback function that a shell applica- 
tion can use to receive useful notifications from the system. 


Parameters code 


Specifies a shell-notification code. This parameter can be one of the following 


values: 
Value 
HSHELL_ACTIVATESHELLWINDOW 


HSHELL_WINDOWCREATED 


HSHELL_WINDOWDESTROYED 


wParam 


Meaning 


The shell application should activate 
its main window. 


A top-level, unowned window was 
created. The window exists when the 
system calls a ShellProc function. 


A top-level, unowned window is 
about to be destroyed. The window 
still exists when the system calls a 
ShellProc function. 


Specifies additional information the shell application may need. The interpreta- 
tion of this parameter depends on the value of the code parameter, as follows: 


code 


HSHELL_ACTIVATESHELLWINDOW 
HSHELT WINDOWCREATED 


HSHELL_WINDOWDESTROYED 


wParam 

Not used. 

Snecifies the handle of the window 
being created. 

Specifies the handle of the window 


being destroyed. 


Return Value 


Comments 


See Also 


ShowCaret 
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lParam 
Reserved; not used. 


The return value Should be zero. 


An application must install this callback function by specifying the WH_SHELL 
filter type and the procedure-instance address of the callback function in a call to 
the SetWindowsHook function. 


ShellProc is a placeholder for the library-defined function name. The actual name 


must be exported by including it in an EXPORTS statement in the library’s 
module-definition file. 


DefHookProc, SendMessage, SetWindowsHook 


[ 2.x | 


void ShowCaret(hwnd) 


HWND hwnd; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of window with caret */ 


The ShowCaret function shows the caret on the screen at the caret’s current posi- 
tion. Once shown, the caret begins flashing automatically. 


hwnd 7 | | 
Identifies the window that owns the caret. This parameter can be set to NULL 
to indirectly specify the window in the current task that owns the caret. 


This function does not return a value. 


The ShowCaret function shows the caret only if it has a current shape and has not 
been hidden two or more times consecutively. If the given window does not own 


the caret, the caret is not shown. If the hwnd parameter is NULL, the ShowCaret 


function shows the caret only if it is owned by a window in the current task. 


Hiding the caret is cumulative. If the HideCaret function has been called five — 
times consecutively, ShowCaret must be called five times to show the caret. 


The caret is a shared resource. A window should show the caret only when it has 
the input focus or is active. | 


CreateCaret, GetActiveWindow, GetFocus, HideCaret 
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ShowCursor | [2x | 


int ShowCursor(/Show) 
BOOL fShow; /* cursor visibility flag / 


The ShowCursor function shows or hides the cursor. 


Parameters fShow 
7 Specifies whether the display count is incremented or decremented (increased 
or decreased by one). If this parameter is TRUE, the display count is incre- 
mented; otherwise, it is decremented. 


Return Value The return value specifies the new display count, if the function 1s successful. 


Comments A cursor show-level count is Kept internally. It is incremented by a show operation 
and decremented by a hide operation. The cursor is visible only if the count is 
greater than or equal to zero. If a mouse exists, the initial setting of the cursor 
show level is zero; otherwise, it is —1. 


The cursor is a shared resource. A window that hides the cursor should show it 
before the cursor leaves its client area or before the window relinquishes control to 
another window. 


See Also SetCursor 


ShowOwnedPopups [2x | 


void ShowOwnedPopups(hwnd, fShow) 
HWND hwnd; /* handle of window ** / 
BOOL Show; /* window visibility flag sa 


The ShowOwnedPopups function shows or hides all pop-up windows owned by 
the given window. 


Parameters — hwnd | 
Identifies the window that owns the pop-up windows to be shown or hidden. 
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fShow — 


Specifies whether pop-up windows are to be shown or hidden. If this parameter 
is TRUE, all hidden pop-up windows are shown. If this parameter is FALSE, 
all visible pop-up windows are hidden. 


Return Value This function does not return a value. 


See Also IsWindowVisible, Show Window 


ShowScrollBar | | Pax] 
void ShowScrollBar(hwnd, fnBar, fShow) . 
HWND hwna; /* handle of window with scroll bar */ 


int fnBar; /* scroll-bar flag | 
BOOL Show; /* scroll-bar visibility flag | 


The ShowScrollBar function shows or hides a scroll bar. 


Parameters hwnd 
: Identifies a scroll bar or a window that contains a scroll bar in its nonclient 
area, depending on the value of the fnBar parameter. If fnBar is SB_CTL, hwnd 
identifies a scroll bar. If fnBar is SB_HORZ, SB_VERT, or SB_BOTH, hwnd 
identifies a window that has a scroll bar i in its nonclient area. 


fnBar | 
Specifies whether the scroll bar is a control or part of a window’s nonclient 
area. If the scroll bar is part of the nonclient area, fnBar also indicates whether 
the scroll bar is positioned horizontally, vertically, or both. This parameter can 
be one of the following values: | | 


Value — Meaning 


SB_BOTH Specifies the window’s horizontal and vertical scroll bars. 

SB_CTL Specifies that the hwnd parameter identifies a scroll bar control. 
- SB_HORZ __ Specifies the window’s horizontal scroll bar. 

SB_VERT Specifies the window’s vertical scroll bar. 


— fShow — 
Specifies whether the scroll bar is - shown or hidden: If this parameter is TRUE, 
the scroll bar is shown; otherwise, it is hidden. 
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Return Value This function does not return a value. 


Comments An application should not call this function to hide a scroll bar while processing a 
: -scroll-bar notification message. 


See Also GetScrollPos, GetScrollRange, ScrollWindow, SetScrollPos, SetScrollRange 


ShowWindow ra 


BOOL Show Window(hwnd, nCmdShow) 
HWND hwnd; /* handle of window */ 
int nCmdShow; /* window visibility flag lf 


The ShowWindow function sets the given window’s visibility state. 


Parameters hwnd 
Identifies the window. 
nCmdShow 


Specifies how the window is to be shown. This parameter can be one of the fol- 
lowing values: 


Value Meaning 
SW_HIDE Hides the window and passes activation to 
| : another window. | 
SW_MINIMIZE Minimizes the specified window and activates the 
| top-level window in the system’s list. 
SW_RESTORE Activates and displays a window. If the window 


— 18 minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_SHOWNORMAL). 


SW_SHOW Activates a window and displays it in its current 
| | : size and position. 
SW_SHOWMAXIMIZED Activates a window and displays it as a maxi- 
mized window. , 
SW_SHOWMINIMIZED Activates a window and displays it as an icon. 


SW_SHOWMINNOACTIVE Displays a window as an icon. The window that is" 
currently active remains active. 


~ SW_SHOWNA Displays a window in its current state. The win- 
dow that is currently active remains active. 


Return Value 


Comments | 


See Also 
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Value Meaning 


SW_SHOWNOACTIVATE Displays a window in its most recent size and 
| position. The window that is currently active re- 
_ mains active. 
SW_SHOWNORMAL Activates and displays a window. If the window 
is minimized or maximized, Windows restores it 


to its original size and position (same as 
SW_RESTORE). 


The return value is nonzero if the window was previously visible. It is zero if the 
window was previously hidden. 


The Show Window function must be called only once per application using the 
nCmdShow parameter from the WinMain function. Subsequent calls toShow- | 
Window must use one of the values listed in the preceding list, instead of the one | 
specified by the nCmdShow parameter from WinMain. 


IsWindowVisible, ShowOwnedPopups 


SizeofResource _ = 


DWORD SizeofResource(hinst, hrsrc) 


- HINSTANCE hinst; 


HRSRC hrsrc; 


Parameters 


Return Value 
Comments | 


See Also 


/* handle of module with resource */ 
/* handle of resource | */ 


The SizeofResource function returns the size, in bytes, of the given resource. 


hinst . | : 
Identifies the instance of the module whose executable file contains the re- 
source. 


hrsrc 
Identifies the resource. This handle must have been created a. by using the 
FindResource function. | 


The return value specifies the number of bytes in the resource, if the function is 
successful. It is zero if the resource cannot be found. } 


The value returned may be larger than the resource due to alignment. An applica- 
tion should not rely upon this value for the exact size of a resource. 


AccessResource, FindResource 
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SpoolFile rat] 


HANDLE SpoolFile(/pszPrinter, IpszPort, IpszJob, IpszFile) 
LPSTR [pszPrinter; /* printer name ed 


LPSTR [pszPort; /* port name =) 
LPSTR IpszJob; /* job name i 
LPSTR IpszFile; /* file name “ey 


The SpoolFile function puts a file into the spooler queue. This function is typically 
used by device drivers. 


Parameters lpszPrinter 
Points to a null-terminated string specifying the printer name—for example, 
“HP LasterJet IIP”’. , 


lpszPort 
Points to a null-terminated string specifying the local name—for example, 
“LPT 1:”. This must be a local port. 


[pszJob 
Points to a null-terminated string specifying the name of the print job for the 
spooler. This string cannot be longer than 32 characters, mee the null- 
terminating character. 


lpszFile 
Points to a null-terminated string specifying the path and filename of the file to 
put in the spooler queue. This file contains raw printer data. 


Return Value The return value is the global handle that is passed to the spooler, if the function is 
successful. Otherwise, it is an error value, which can be one of the following: 


SP_APPABORT 
SP_ERROR 
SP_NOTREPORTED 
SP_OUTOFDISK 
SP_OUTOFMEMORY 
SP_USERABORT 


Comments Applications should ensure that the spooler is enabled before calling the SpoolFile 
function. | 


StackTraceCSIPFirst 911 


stackTraceCSIPFirst Eu 


#include <toolhelp.h> 

BOOL StackTraceCSIPFirst(lpste, wSS, wCS, wIP, wBP) 

STACKTRACEENTRY FAR* I[pste; /* address of stack-frame structure si | 
WORD wSSs; /* value of SS register 7} 
WORD wCs; /* value of CS register **/ 
WORD wiIP; /* value of IP register ee | 
WORD wBP; /* value of BP register */ 


Parameters 


Return Value 


The StackTraceCSIPFirst function fills the specified structure with information | 
that describes the specified stack frame. 


Ipste 
Points tt aSTACKTRACEENTRY structure to receive information about the 
stack. The STACKTRACEENTRY structure has the following form: 


#tinclude <toolhelp.h> 
typedef struct tagSTACKTRACEENTRY { /* ste */ 


DWORD dwSize; 
HTASK hTask; 


WORD wSS; 
WORD WBP; 
WORD wCS; 
WORD wIP; 


HMODULE hModule; 
WORD wSegment; 
WORD wFlags; 

} STACKTRACEENTRY ; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3: 


wss 
Contains the value in the SS register. This value is used with the wBP value to 
determine the next entry in the stack trace. 


wCs 
Contains the value in the CS register of the first stack frame. 


wIP | 
Contains the value in the IP register of the first stack frame. 


wBP 
Contains the sass in the BP register. This value is used with the wSS value to 
_ determine the next entry in the stack trace. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 
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Comments The StackTraceFirst function can be used to begin a stack trace of any task ex- 
| cept the current task. When a task is inactive, the kernel maintains its state, includ- 
ing its current stack, stack pointer, CS and IP values, and BP value. The kernel 
does not maintain these values for the current task. Therefore, when a stack trace 
is done on the current task, the application must use StackTraceCSIPFirst to 
begin a stack trace. An application can continue to trace through the stack by using 
the StackTraceNext function. | | 


Before calling StackTraceCSIPFirst, an application must initialize the STACK- 
TRACEENTRY structure and specify its size, in bytes, in the dwSize member. 


See Also StackTraceNext, StackTraceFirst 


StackTraceFirst EXE 


#include <toolhelp.h> 

BOOL StackTraceFirst(/pste, htask) | 

STACKTRACEENTRY FAR* lpste; /* address of stack-frame structure Th 
HTASK htask; | /* handle of task */ 


The StackTraceFirst function fills the specified structure with information that 
describes the first stack frame for the given task. 


Parameters Ipste 
Points tt aSTACKTRACEENTRY structure to receive information about the 
task’s first stack frame. The STACKTRACEENTRY structure has the follow- 
ing form: 


#include <toolhelp.h> 


typedef struct sane { /* ste */ 
DWORD = dwSize; | 
HTASK ~~ hTask; 


WORD wSS; 
WORD wBP; 
WORD wCS; 
WORD wIP; 


LMA Cc hMod: ita 
Lo 1OUuUuUICc, 


WORD wSegment; 
WORD wF lags; 
4 STACKTRACEENTRY 
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For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


htask 
Identifies the task whose stack information is to be described. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. | 


Comments The StackTraceFirst function can be used to begin a stack trace of any task ex- 

7 cept the current task. When a task is inactive, the kernel maintains its state, includ- 
ing its current stack, stack pointer, CS and IP values, and BP value. The kernel 
does not maintain these values for the current task. Therefore, when a stack trace 
is done on the current task, the application must use the StackTraceCSIPFirst 
function to begin a stack trace. An application can continue to trace through the 
stack by using the StackTraceNext function. © a 


Before calling StackTraceFirst, an application must initialize the STACK- 
TRACEENTRY structure and specify its size, in bytes, in the dwSize member. 


See Also StackTraceCSIPFirst, StackTraceNext 


StackTraceNext ca oy Ba] 
#include <toolhelp.h> 


BOOL StackTraceNext(/pste) : 
STACKTRACEENTRY FAR* [pste; /* address of stack-frame structure sf 


The StackTraceNext function fills the specified structure with information that de- 
scribes the next stack frame in a stack trace. | 


Parameters Ipste | | | | 

| Points to a STACKTRACEENTRY structure to receive information about the 
next stack frame. The STACKTRACEENTRY structure has the following 
form: | 


#Hinclude <toolhelp.h> 


typedef struct tagSTACKTRACEENTRY { /* ste */ 
DWORD dwSize; ; 
HTASK — hTask; 
WORD wSS; 
WORD WwBP ; 
WORD wCS; 
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WORD wIP; 
HMODULE hModule; 
WORD wSegment; 
WORD wFlags; 

} STACKTRACEENTRY ; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The StackTraceNext function can be used to continue a stack trace started by 
using the StackTraceFirst or Stack TraceCSIPFirst function. 


See Also StackTraceCSIPFirst, StackTraceFirst, STACKTRACEENTRY 


StartDoc | | 3.1 | 


int StartDoc(hdc, [pdi) 
HDC hdc; /* handle of device context ey 
DOCINFO FAR? [pdi; /* pointer to DOCINFO structure a | 


The StartDoc function starts a print job. For Windows version 3.1, this function 
replaces the STARTDOC printer escape. 


Parameters hdc 
Identifies the device context for the print job. 
[pdi 
Points to a DOCINFO structure containing the name of the document file and 
the name of the output file. The DOCINFO structure has the following form: 


typedef struct { /* di */ 
int cbSize; 
LPCSTR JlpszDocName; 
~ LPCSTR  IpszOutput; 
} DOCINFO; — 


‘For a full deccrintionn of thic ctructure cee the Mirracatt Windaws Prnaram- 
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mer’ s Reference, Volume 3. 


Return Value The return value is positive if the function is successful. means. it is 
~SP_ERROR. 
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Comments Applications should call the StartDoc function immediately before beginning a 
print job. Using this function ensures that documents containing more than one 
page are not interspersed with other print jobs. 


The StartDoc function should not be used inside metafiles. 


See Also EndDoc, Escape 


-StartPage | EXE 


int StartPage(hdc) 
HDC hdc; /* handle of device context */ 


The StartPage function prepares the printer driver to accept data. 


Parameters hdc 
Identifies the device context for the print job. 


Return Value The return value is greater than zero if the function is successful. It is less than or | 
equal to zero if an error occurs. | | 


Comments The system disables the ResetDC function between calls to the StartPage and — 
EndPage functions. This means that applications cannot change the device mode 
except at page boundaries. 


See Also EndPage, Escape, ResetDC 


StartSound — Ae oa peer Ta 


int StartSound(void) 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 
media Programmer’ s Reference. 
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StopSound | [2x] 


int StopSound(void) 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 
media Programmer’s Reference. 


StretchBlt arr 


BOOL StretchBlt(hdcDest, nX OriginDest, nYOriginDest, nWidthDest, nHeightDest, hdcSre, 
nXOriginSrc, nYOriginSrc, nWidthSrc, nHeightSrc, fdwRop) 


HDC hdcDest; /* destination device-context handle sf 
int nXOriginDest; /* x-coordinate of origin of destination rectangle sy 
int nYOriginDest; /* y-coordinate of origin of destination rectangle a 
int nWidthDest; /* width of destination rectangle i 
int nHeightDest; /* height of destination rectangle */ 
HDC hdcSrc; /* source device-context handle */ 
int nXOriginSrc3 /* x-coordinate of origin of source rectangle =] 
int nYOriginSrc; /* y-coordinate of origin of source rectangle */ 
int nWidthSrc; /* width of source rectangle i) 
int nHeightSrc; /* height of source rectangle */ 
DWORD /fdwRop; /* raster operation : 9 


The StretchBit function copies a bitmap from a source rectangle into a destination 
rectangle, stretching or compressing the bitmap if necessary to fit the dimensions 
of the destination rectangle. The StretchBlt function uses the stretching mode of 
the destination device context (set by the SetStretchBltMode function) to deter- 
mine how to stretch or compress the bitmap. 


Parameters hdcDest 
| Identifies the device context to receive the bitmap. 
nXOriginDest 


Specifies the logical x-coordinate of the upper-left corner of the destination 
rectangle. 


n VOri gin De ct 
, Specifies the logical y-coordinate of the Upper-lent corner of the destination 
rectangle. | 


nWidthDest | | 
Specifies the width, in logical units, of the destination rectangle. 
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nHeightDest 
Specifies the height, in logical units, of the destination rectangle. 


hdcSrce 
Identifies the device context that contains the source bitmap. 


nX OriginSrc 
Specifies the logical x-coordinate of the upper-left corner of the source 
rectangle. 


nYOriginSrc 
Specifies the logical y-coordinate of the upper-left corner of the source 
rectangle. 


nWidthSrc | 
Specifies the width, in logical units, of the source rectangle. 


nHeightSre 
Specifies the height, in logical units, of the source netanee 


fdwRop 


Specifies the raster operation to be performed. Raster-operation codes define 
how the graphics device interface (GDI) combines colors in output operations 

that involve a current brush, a possible source bitmap, and a destination bitmap. 
This parameter can be one of the following values: 


Code 


BLACKNESS 
DSTINVERT 
MERGECOPY 


MERGEPAINT 


NOTSRCCOPY 
NOTSRCERASE 


PATCOPY 
PATINVERT 


_ PATPAINT 


SRCAND 


SRCCOPY 
SRCERASE — 


Description 


Turns all output black. 
Inverts the destination bitmap. 


Combines the pattern and the source bitmap by using the 
Boolean AND operator. 


Combines the inverted source bitmap with the destination bit- 
map by using the Boolean OR operator. 


Copies the inverted source bitmap to the destination. 


Inverts the result of combining the destination and source bit- 
maps by using the Boolean OR operator. 


Copies the pattern to the destination bitmap. 


Combines the destination bitmap wath the pattern by using the 
Boolean XOR operator. 


Combines the inverted source bitmap with the pattern by 
using the Boolean OR operator. Combines the result of this 
operation with the destination bitmap by using the Boolean 
OR operator. 


Combines pixels of the destination fd source nee by 
using the Boolean AND operator. - 


Copies the source bitmap to the destination bitmap. 


Inverts the destination bitmap and combines the result with 
the source bitmap by using the Boolean AND operator. 
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Return Value 


Comments 


Example 


Code 2 Description 
SRCINVERT Combines pixels of the destination and source bitmaps by 
7 using the Boolean XOR operator. 
SRCPAINT Combines pixels of the destination and source bitmaps by 
using the Boolean OR operator. 
WHITENESS Turns all output white. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The StretchBlt function stretches or compresses the source bitmap in memory and 
then copies the result to the destination. If a pattern is to be merged with the result, 
it is not merged until the stretched source bitmap is copied to the destination. 


If a brush is used, it is the selected brush in the destination device context. 


The destination coordinates are transformed according to the destination device 
context; the source coordinates are transformed according to the source device con- 


text. 


If the destination, source, and pattern bitmaps do not have the same color format, 
StretchBIt converts the source and pattern bitmaps to match the destination bit- 
maps. The foreground and background colors of the destination device context are 
used in the conversion. 


If StretchBlt must convert a monochrome bitmap to color, it sets white bits (1) to 
the background color and black bits (0) to the foreground color. To convert color. 
to monochrome, it sets pixels that match the background color to white (1) and 
sets all other pixels to black (0). The foreground and background colors of the 
device context with color are used. | 


StretchBIt creates a mirror image of a bitmap if the signs of the nWidthSrc and 
nWidthDest or nHeightSrc and nHeightDest parameters differ. If nWidthSrc and 
nWidthDest have different signs, the function creates a mirror image of the bitmap 
along the x-axis. If nHeightSrc and nHeightDest have different signs, the function 
creates a mirror image of the bitmap along the y-axis. 


Not all devices support the StretchBlt function. Applications can discover 
whether a device supports StretchBIt by calling the GetDeviceCaps function and — 
specifying the RASTERCAPS index. 


The following example retrieves the handle of the desktop window and uses it to 
create a device context. After retrieving the dimensions of the desktop window, 
the example calls the StretchBlt function to copy the desktop bitmap into a 


smaller rectangle in the destination device context. 
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HWND hwndDesktop; 

HDC hdcLocal; 

RECT rc; 

hwndDesktop = GetDesktopWindow( ); 
hdcLocal = GetDC(hwndDesktop) ; 
GetWindowRect(GetDesktopWindow(), &rc); 


StretchBlt(hdc, 10, 10, 138, 106, | 
hdcLocal, 0, @, rc.right, rc.bottom, SRCCOPY); 


ReleaseDC(hwndDesktop, hdcLocal); 


See Also | | BitBlt, GetDeviceCaps, SetStretchBltMode, StretchDIBits 


-StretchDIBits om 


int StretchDIBits(hdc, XDest, YDest, cxDest, cyDest, XSrc, YSre, cxSrc, cySrc, [pvBits, lpbmi, 


fuColorUse, jawhep) : | 
HDC hdc; /* handle of device context */ 
int XDest; /* x-coordinate of destination rectangle **/ 
int YDest; /* y-coordinate of destination rectangle **/ 
int cxDest; _ /* width of destination rectangle i 
int cyDest; /* height of destination rectangle */ 
int XSrc;3 /* x-coordinate of source rectangle => 7) 
int YSrc; /* y-coordinate of source rectangle mf 
int cxSrc; /* width of source rectangle **/ 
int cySrc3 | /* height of source rectangle =] 
const void FAR* [pvBits; /* address of buffer with DIB bits | 
~ LPBITMAPINFO [pbmi; /* address of structure with bitmap data at | 
_ UINT fuColorUse; | /* RGB or palette indices | "|, 
DWORD /fdwRop; /* raster operation i 


The StretchDIBits function moves a device-independent bitmap (DIB) from a 
source rectangle into a destination rectangle, stretching or compressing the bitmap 
if necessary to fit the dimensions of the destination rectangle. | 


Parameters  §=—S hhc 
| | Identifies the destination device context for a screen surface or memory bitmap. 


XDest . | | 
Specifies the logical X- Coordinate: oft the destination rectangle. 


YDest : 
Syeln the logical y- coordinate of the destination rectangle. 
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Return Value 


cxDest 
Specifies the logical x-extent of the destination rectangle. 


cyDest 
Specifies the logical y-extent of the destination rectangle. 


XSrc 
Specifies the x-coordinate, in pixels, of the source rectangle in the DIB. 


YSrc | 
Specifies the y-coordinate, in pixels, of the source rectangle in the DIB. 


cxSrc | 
Specifies the width, in pixels, of the source rectangle in the DIB. 


cySrc 

Specifies the height, in pixels, of the source rectangle in the DIB. 
[pvBits | | 

Points to the DIB bits that are stored as an array of bytes. 


~ [pbmi 


Points to a BITMAPINFO structure that contains information about the DIB. 
The BITMAPINFO structure has the following form: 


typedef struct tagBITMAPINFO { /* bmi */ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 

} BITMAPINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


fuColorUse 
Specifies whether the bmiColors member of the /pbmi parameter contains ex- 


plicit RGB (red-green-blue) values or indices into the currently realized logical 


palette. The fuColorUse parameter can be one of the following values: 
Value Meaning 


DIB_PAL_COLORS The color table consists of an array of 16-bit indices into 
the currently realized logical palette. | 


DIB_RGB_COLORS The color table contains literal RGB values. 


JdwRop 7 


Specifies the raster operation to be performed. Raster-operation codes define 
how the graphics device interface (GDI) combines colors in output operations 


— that involve a current brush, a possible source bitmap, and a destination bitmap. 


For a list of raster-operation codes, see the description of the BitBlt function. 
For a complete list of the raster operations, see the Microsoft Windows Pro- 
grammer’s Reference, Volume 4. 


The return value is the number of scan lines copied, if the function is successful. 
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Comments The StretchDIBits function uses the stretching mode of the destination device 
7 context (set by the SetStretchBltMode function) to determine how to stretch or 
compress the bitmap. 


The origin of the coordinate system for a device-independent bitmap is the lower- 
left corner. The origin of the coordinates of the destination rectangle depends on 
the current mapping mode of the device context. 


StretchDIBits creates a mirror image of a bitmap if the signs of the cxSrc and 
cxDest parameters or the cySrc and cyDest parameters differ. If cxSrc and cxDest 
have different signs, the function creates a mirror image of the bitmap along the 
x-axis. If cySrc and cyDest have different signs, the function creates a mirror 
image of the bitmap along the y-axis. 


See Also SetMapMode, SetStretchBltMode 


SubtractRect — [34] 


BOOL SubtractRect(/prcDest, lprcSource1, lprcSource2) 


RECT FAR®* IprcDest; /* pointer to destination rectangle a] 
const RECT FAR® IprcSource1; /* pointer to rect. to subtract from = */ 
const RECT FAR® IprcSource?2; /* pointer to rect. to subtract ef 


The SubtractRect function retrieves the coordinates of a rectangle by subtracting 
one rectangle from another. 


_ Parameters IprcDest 
| Points to the RECT structure to receive the dimensions of the new Waeeaunle. 
The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the M icrosoft Windows Program- 
mer’s Reference, Volume 3. , | | 


- IprcSourcel © | | | 
Points to the RECT structure from which a rechingle’ is to be subtracted. 
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_lprcSource2 : 7 
Points to the RECT structure that is to be subtracted from the rectangle pointed 
to by the lprcSource! parameter. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The rectangle specified by the JprcSource2 parameter is subtracted from the rec- © 
tangle specified by IprcSource1 only when the rectangles intersect completely in 
either the x- or y-direction. For example, if IprcSourcel were (10,10, 100,100) and 
lprcSource2 were (50,50, 150,150), the rectangle pointed to by /prcDest would 
contain the same coordinates as lprcSource] when the function returned. If 
lprcSourcel were (10,10, 100,100) and lprcSource2 were (50,10, 150,150), how- 
ever, the rectangle pointed to by JprcDest would contain the coordinates (10,10, 
50,100) when the function returned. 


See Also _ IntersectRect, UnionRect 


SwapMouseButton _ 2x | 


BOOL SwapMouseButton({Swap) 
~ BOOL fSwap; /* reverse or restore buttons */ 


The SwapMouseButton function reverses the meaning of left and right mouse but- 
tons. 


Parameters jfSwap | 
| Specifies whether the button meanings are reversed or restored. If this parame- . 
ter is TRUE, the left button generates right-button mouse messages and the 
right button generates left-button messages. If this parameter is FALSE, the but- 
tons are restored to their original meanings. 


Return Value The return value specifies the meaning of the mouse buttons immediately before 


the function is called. It is nonzero if the meaning was reversed. Otherwise, it is 
zero. 
Comments — Button swanning is provided as a convenience to neonle who use the mouse with 


their left hands. The SwapMouseButton function is usually called by Control 
Panel only. Although an application is free to call the function, the mouse is a 
shared resource and reversing the meaning of the mouse button affects all 
applications. | 
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Example The following example swaps the mouse buttons, depending on the check state of 
a check box: | 


BOOL fSwap; 
fSwap = (BOOL) SendDigItemMessage(hdlg, IDD_SWAP, 


BM_GETCHECK, @, QL); 
SwapMouseButton(fSwap); 


SwapRecording | 


void SwapRecording(/uF lag) 
UINT jfuFlag; /* whether to start or stop swap recording i 


The SwapRecording function starts or stops recording data about memory swap- 
ping. Because this function can be used only in real mode, it cannot be used with 
Windows 3.1. 


SwitchStackBack te 


void SwitchStackBack(void) 


The SwitchStackBack function restores the stack of the current task, canceling 
the effect of the SwitchStackTo function. 


Parameters © This function has no parameters. 
Return Value This function does not return a value. 
Comments SwitchStackBack preserves the contents of the AX:DX registers when it returns. 


See Also , SwitchStackTo 


924 SwitchStackTo 


SwitchStackTo 


void SwitchStackTo(uStackSegment, uStackPointer, uStackTop) 


UINT uStackSegment; /* new stack data segment st 
UINT uStackPointer; /* offset of beginning of stack i a 
UINT uStackTop; /* offset of top of stack */ 
The SwitchStackTo function changes the stack of the current task to the specified 
data segment. 
Parameters uStackSegment 
Specifies the data segment to contain the stack. 
uStackPointer | 
Specifies the offset to the beginning of the stack in the data segment. 
uStackTop 
Specifies the offset to the top of the stack from the beginning of the stack. 
Return Value This function does not return a value. 
Comments | Dynamic-link libraries (DLLs) do not have private stacks; instead, a DLL uses the 


stack of the task that calls the library. As a result, a DLL function fails if it treats 
the contents of the data-segment (DS) and stack-segment (SS) registers as equal. A 
task can call SwitchStackTo before calling a function in a DLL that treats the SS 
and DS registers as equal. When the DLL function returns, the task must then call 
the SwitchStackBack function to redirect its stack to its own data segment. 


A DLL can also call SwitchStackTo before calling a function that assumes SS 
and DS to be equal and then call SwitchStackBack before returning to the task 
that called the DLL function. 


Calls to SwitchStackTo and SwitchStackBack cannot be nested. That is, after 


calling SwitchStackTo, an application must call SwitchStackBack before calling 
oy eneto again. | 


SeeAlso jg _SwitchStackBack 
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SyncAlliVoices a [2x | 


int SyncAllVoices(void) 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 
media Programmer’s Reference. 


‘SysMsgProc a ra 


LRESULT CALLBACK SysMsgProc(code, wParam, lParam) 


— int code; /* message type **/ 
WPARAM wParam; _‘/* undefined */ 
LPARAM /Param; /* pointer to an MSG structure © */ 


The SysMsgProc function is a library-defined callback function that the system 
calls after a dialog box, message box, or menu has retrieved a message, but before 
the message is processed. The callback function can process or modify messages 
for any application in the system. 


Parameters code 
Specifies the type of message being processed. This parameter can be one of 
the following values: 


Value Meaning 


MSGF_DIALOGBOX Messages inside a dialog box or message box procedure 
are being processed. 


MSGF_MENU | Keyboard and mouse messages in a menu are being 
: processed. 


If the code parameter is less than zero, the callback function must pass the mes- 
sage to the CallNextHookEx function without further processing and return the 
value returned by CallNextHookEx. 


wParam 
Must be NULL. 


[Param 
Points to the MSG structure to contain the message. The MSG structure has the 
following form: 
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~ Return Value 


Comments 


See Also 
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typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD' time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


The return value should be nonzero if the function processes the message. Other- 
wise, it should be zero. 


This callback function must be in a dynamic-link library (DLL). 


An application must install this callback function by specifying the _ 
WH_SYSMSGFILTER filter type and the procedure-instance address of the call- © 
back function in a call to the SetWindowsHookEx function. 


SysMsgProc is a placeholder for the library- defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the library’s 
module-definition file. | 


CallNextHookEx, MessageBox, Set WindowsHookEx 


#include <toolhelp.h> 


BOOL SystemHeapInfo(/pshi) | 
SYSHEAPINFO FAR* Ipshi; /* address of heap-info structure i 


Parameters 


The SystemHeapInfo function fills the specified structure with information that 
describes the USER.EXE and GDI.EXE heaps. 


Inshi 
Points to a SYSHEAPINFO structure to receive information about the USER 
and GDI heaps. The SYSHEAPINFO structure has the following form: 
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#include <toolhelp.h> 


typedef struct tagSYSHEAPINFO { /* shi */ 
DWORD dwSize; | 
WORD wUserFreePercent; 
WORD wGDIFreePercent; 
HGLOBAL hUserSegment; 
HGLOBAL hGDISegment; 
} SYSHEAPINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments This function is included for advisory purposes. Before calling SystemHeapInfo, 


an application must initialize the SYSHEAPINFO structure and specily its size, 
in mys: in the dwSize member. 
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BOOL SystemParametersInfo(uAction, uParam, lpvParam, fuWinIni) 


UINT wAction; /* system parameter to query or set */ 
UINT uParam; /* depends on system parameter */ 
void FAR* [pvParam; /* depends on system parameter a} 
UINT fuWinIni; _ [*® WIN.INI update flag **/ 


The SystemParametersInfo function queries or sets system-wide parameters. 
This function can also update the WIN.INI file while setting a parameter. 


Parameters © uAction 
Specifies the system-wide parameter to query or set. This parameter can be one 
of the following values: 


Value . Meaning 

SPI_GETBEEP | Retrieves a BOOL value that indicates 
| __ whether the warning beep is on or off. 

SPI_GETBORDER Retrieves the border multiplying factor 


that determines the width of a window’s 
sizing border. 


SPI_GETFASTTASKS WITCH Determines whether fast task switching 
is on or off. 
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Value 


SPI_GETGRIDGRANULARITY 
SPILGETICONTITLELOGFONT 
SPI_GETICONTITLEWRAP | 
SPI_GETKEYB OARDDELAY 
SPI_GETKEYBOARDSPEED 


SPI_GETMENUDROPALIGNMENT 
SPI_GETMOUSE 


SPI_GETSCREENSAVEACTIVE 


SPI_GETSCREENSAVETIMEOUT 
SPI_ICONHORIZONTALSPACING 
SPIICONVERTICALSPACING 
SPI_LANGDRIVER 


SPI_SETBEEP 
SPI_SETBORDER 


SPI_SETDESKPATTERN 


SPI_SETDESKWALLPAPER | 


SPI_SETDOUBLECLKHEIGHT 


_ SPIL_SETDOUBLECLICKTIME 


Meaning 

Retrieves the current granularity value of 
the desktop sizing grid. 

Retrieves the logical-font information for 
the current icon-title font. 

Determines whether icon-title wrapping 
is on or off. 

Retrieves the keyboard repeat-delay 
setting. 

Retrieves the keyboard repeat-speed 
setting. 

Determines whether pop-up menus are 
left-aligned or right-aligned relative to 
the corresponding menu-bar item. 


Retrieves the mouse speed and the 


mouse threshold values, which Windows 


uses to calculate mouse acceleration. 


Retrieves a BOOL value that indicates 
whether screen saving is on or off. 


Retrieves the screen-saver time-out value. 
Sets the width, in pixels, of an icon cell. 
Sets the height, in pixels, of an icon cell. 


Forces the user to load a new language 
driver. 


Turns the warning beep on or off. 


Sets the border multiplying factor that de- 
termines the width of a window’s sizing 
border. 


Sets the current desktop pattern to the 
value specified in the Pattern entry in the 
WIN.INI file or to the pattern specified 
by the /pvParam parameter. 


Specifies the filename that contains the 
bitmap to be used as the desktop wall- 
paper. 

Sets the height of the rectangle within 
which the second click of a double-click 
must fall for it to be registered as a 
AAT. ALL AL 

Sets the double-click time for the mouse. 
The double-click time is the maximum 
number of milliseconds that may occur 
between the first and second clicks of a 
double-click. 


Value 


SPISETDOUBLECLK WIDTH 


SPI_SETFASTTASKS WITCH 
SPI_SETGRIDGRANULARITY 


SPL SETICONTITLELOGFONT 
SPISETICONTITLEWRAP 
SPISETKEYBOARDDELAY 
SPILSETKEYBOARDSPEED 
SPILSETMENUDROPALIGNMENT 


SPI. SETMOUSE 
SPL SETMOUSEBUTTONSWAP 


SPI_SETSCREENSAVEACTIVE 
SPI_SETSCREENSAVETIMEOUT 


uParam 


Comments section. 


lpvParam 


Comments section. 
fuWinIni 
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Meaning 


Sets the width of the rectangle in which 
the second click of a double-click must 
fall to be registered as a double-click. 


Turns fast task switching on or off. 

Sets the granularity of the desktop sizing 
grid. 

Sets the font that is used for icon titles. 
Turns icon-title wrapping on or off. 

Sets the keyboard repeat-delay setting. 
Sets the keyboard repeat-speed setting. 


Sets the alignment value of pop-up 
menus. 


Sets the mouse speed and the x and y 
mouse-threshold values. 


Swaps or restores the meaning of the left 
and right mouse buttons. 


Sets the state of the screen saver. 
Sets the screen-saver time-out value. 


Depends on the uAction parameter. For more information, see the following 
Depends on the uAction parameter. For more information, see the following 


If a system parameter is being set, specifies whether the WIN.INI file is up- 
dated, and if so, whether the WM_WININICHANGE message 1s broadcast to 
all top-level windows to notify them of the change. This parameter can be a 
combination of the following values: 


Value © | Meaning | | 
SPIF_UPDATEINIFILE Writes the new system-wide parameter setting 
to the WIN INI file. 


SPIF_SENDWININICHANGE Broadcasts a WM_WININICHANGE message 
after WIN.INI is updated. This flag has no ef- 


fect if SPIF_UPDATEINIFILE is not specified. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The SystemParameterInfo function is intended for applications, such as Control 
: Panel, that allow the user to customize the Windows environment. 


930 SystemParametersinfo 


The following table describes the uParam and [pvParam parameters for each 


SPL_ constant: 


Constant 


SPL GETBEEP 
SPL GETBORDER 


SPI_GETFASTTASKS WITCH 


SPI_GETGRIDGRANULARITY 
SPI_GETICONTITLELOGFONT 


SPI_GETICONTITLEWRAP 


SPI_GETKEYBOARDDELAY 
SPI_GETKEYBOARDSPEED 


SPI_GETMENUDROPALIGNMENT 


SPI_GETMOUSE 


SPI_GETSCREENSAVEACTIVE 


SPI_GETSCREENSAVETIMEOUT 


SPI_ICONHORIZONTALSPACING 


SPL ICONVERTICALSPACING 


uParam 


0 


0 


0 


Size of LOGFONT 
structure 


0 


0 


New width, in 
pixels, for horizontal 
Spacing of icons 


New height, in 
pixels, for vertical 
spacing of icons © 


lpvParam 


Points to a BOOL variable that receives — 
TRUE if the beep is on, FALSE if it is off, 


Points to an integer variable that receives the 
border multiplying factor. 


Points to a BOOL variable that receives 
TRUE if fast task switching is on, FALSE if 
it is off. 


Points to an integer variable that receives the 
grid-granularity value. 


Points to a LOGFONT structure that re- 
ceives the logical-font information. 


Points to a BOOL variable that receives 
TRUE if wrapping is on, FALSE if wrap- 
ping is off. 

Points to an integer variable that receives the 
keyboard repeat-delay setting. 


Points to a WORD variable that receives the 
current keyboard repeat-speed setting. 


Points to a BOOL variable that receives 
TRUE if pop-up menus are right-aligned, 
FALSE if they are left-aligned. 

Points to an integer array name lpiMouse, 
where IpiMouse[0] receives the WIN.INI 
entry MouseThreshold1, lpiMouse[1] re- 
ceives the entry MouseThreshold2, and 
IpiMouse[2] receives the entry MouseSpeed. 


Points to a BOOL variable that receives 
TRUE if the screen saver is active, FALSE if 
it is not. 


Points to an integer variable that receives the 
screen-saver time-out value, in milliseconds. 


Is NULL if the icon cell width, in pixels, is 
returned in wParam. If this value is a pointer 
to an integer, the current horizontal spacing 
is returned in that variable and wParam is 
ignored. | 

Is NULL if the icon cell height, in pixels, is 
returned in uParam. If this value is a pointer 
to an integer, the current vertical spacing is 
returned in that variable and uParamis 
ignored. 


Constant 


SPI_LANGDRIVER 


SPI_LSETBEEP 


SPI_SETBORDER 


SPI_SETDESKPATTERN 


SPI_SETDES KWALLPAPER 
SPI_SETDOUBLECLKHEIGHT 
_ SPILSETDOUBLECLICKTIME 
SPL SETDOUBLECLKWIDTH 
SPI_LSETFASTTASKS WITCH 


SPI_LSETGRIDGRANULARITY 
SPI_SETICONTITLELOGFONT 


SPI_SETICONTITLEWRAP 


SPI_SETKEYBOARDDELAY 


SPI_SETKEYBOARDSPEED — 


uParam 


0 


TRUE = turn the 
beep on; FALSE = 
turn the beep off 
Border multiplying - 
factor 


0 or -1 


0 


Double-click height, 
in pixels 
Double-click time, in 
milliseconds 
Double-click width, 
in pixels 

TRUE = turn on fast 
task switching; 
FALSE = turn it off 
Grid granularity, 
Size of the LOG- 
FONT structure 


TRUE = turn wrap- 


ping on; FALSE = 


turn wrapping off 


Keyboard-delay 
setting 


Repeat-speed setting | 


SystemParametersinfo 


lpvParam | 


- Points to a string containing the new lan- 


guage driver filename. The application | 
should make sure that all other international 
settings remain consistent when changing _ 
the language driver. | 


Is NULL. 


Is NULL. 


Specifies the desktop pattern. If this value is 
NULL and the uParam parameter is —1, the 
value is reread from the WIN.INI file. This 
value can also be a null-terminated string 
(LPSTR) containing a sequence of 8 num- 
bers that represent the new desktop pattern; 
for example, “170 85 170 85 170 85 170 85” 
represents a 50% gray pattern. 

Points to a string that specifies the name of 
the bitmap file. 


Is NULL. 
Is NULL... 
Is NULL. 


Is NULL. 


Points toa LOGFONT structure that de- 
fines the font to use for icon titles. If 
uParam is set to zero and [Param is set to | ; 
NULL, Windows uses the icon-title font and 
spacings that were in effect when Windows 
was Started. | 


Is NULL. — | 


Is NULL. 


Is NULL. 
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Constant | wParam lpvParam 


SPILSETMENUDROPALIGNMENT TRUE = right- Is NULL. 
| | alignment; FALSE = 
- left-alignment : 
SPI_SETMOUSE —6(0 | Points to an integer array named IpiMouse, 
7 where IpiMouse[0] receives the WIN.INI 
entry xMouseThreshold, IpiMouse[1] re- 
ceives the entry yMouseThreshold, and 
IpiMouse[2] receives the entry MouseSpeed. 
SPILSETMOUSEBUTTONS WAP TRUE = reverse the Is NULL. | 
meaning of the left 
and right mouse 
buttons; FALSE = 
restore the buttons 
to their original 
| meanings 
SPI_SETSCREENSAVEACTIVE TRUE = activate Is NULL. 
screen saving; 
FALSE = deactivate 
screen saving 
SPL SETSCREENSAVETIMEOUT Idle time-out dura- Is NULL. 
tion, in seconds, 
before screen is saved 


Example - The following example retrieves the value for the DoubleClickSpeed entry from 
the WIN.INI file and uses the value to initialize an edit control. In this example, 
while the WM_COMMAND message is being processed, the user-specified value 
is retrieved from the edit control and used to set the double-click time. 


char szBuf[32]; 
int iResult; 


case WM _INITDIALOG: 
/* Initialize edit control to the current double-click time. */ 
iResult = GetProfileInt("windows", 
"DoubleClickSpeed", 550); 
jtoa(iResult, szBuf, 10); 


SendDigItemMessage(hdlg, IDD_ DCLKTIME, WM_SETTEXT, @, 
(DWORD) (LPSTR) szBuf); 


. /* Initialize any other controls. */ 


return FALSE; 
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case WM COMMAND: 
Switch(wParam) { 


case IDOK: 

/* Set double-click time to a user-specified value. */ 

SendDlgItemMessage(hdlg, IDD_DCLKTIME, WM GETTEXT, 
sizeof(szBuf), (DWORD) (LPSTR) szBuf); © 

SystemParametersInfo(SPI_SETDOUBLECLICKTIME, atoi(szBuf), 
(LPVOID) NULL, SPIF_UPDATEINIFILE | 
SPIF_SENDWININICHANGE) ; 

. /* Set any other system-wide parameters. */ 


EndDialog(hdlg, TRUE); 
return TRUE; 


‘TabbedTextOut — 


LONG TabbedTextOut(hdc, xPosStart, yPosStart, [pszString, “bString, cTabStops, lpnTabPositions, 


nTabOrigin) | | | 

HDC hdc; /* handle of device context */ 

int xPosStart; /* x-coordinate of starting position ai! 

int yPosStart; /* y-coordinate of starting position */ 

LPCSTR IpszString; /* address of string _» ey 

int cbString; | /* number of characters in string */ 

int cTabStops; _ /* number of tabs in array */ 

int FAR* [pnTabPositions; /* address of array with tab positions =] 

int nTabOrigin; /* x-coordinate for tab expansion | 
The TabbedTextOut function writes a character string at the specified location, 
expanding tabs to the values specified in the array of tab-stop positions. The func- 
tion writes text in the currently selected font. | 

Parameters hdc | 

Identifies the device context. 

xPosStart 


Specifies the logical x-coordinate of the Starting point of the string. 


yPosStart 
_ Specifies the nee y-coordinate of the ae Point of the string. 
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Return Value 


Comments 


Example 


[pszString | 
Points to the character string to be drawn. 


cbString 
Specifies the number of characters in the string. 


cTabStops 
Specifies the number of values in the array of tab-stop positions. 


lpnTabPositions | 
Points to an array containing the tab-stop positions, in device units. The tab 
stops must be sorted in increasing order; the smallest x-value should be the first 
item in the array. 


nTabOrigin 
Specifies the logical x-coordinate of the starting position from which tabs are 
_ expanded. 


The return value is the dimensions of the string, in logical units, if the function is 
successful. The low-order word contains the string width; the high-order word con- 
tains the string height. Otherwise, the return value is zero. 


If the cTabStops parameter is zero and the lpnTabPositions parameter is NULL, 
tabs are expanded to eight times the average character width. 


If cTabStops is 1, the tab stops are separated by the distance specified by the first 
value in the /pnTabPositions array. 


If the [pnTabPositions array contains more than one value, a tab stop is set for 
each value in the array, up to the number specified by cTabStops. 


The nTabOrigin parameter allows an application to call the TabbedTextOut func- 
tion several times for a single line. If the application calls TabbedTextOut more 
than once with the nTabOrigin set to the same value each time, the function ex- 
pands all tabs relative to the position specified by nTabOrigin. 


By default, the current position is not used or updated by the TabbedTextOut 
function. If an application must update the current position when calling Tabbed- 
TextOut, it can call the SetTextAlign function with the wFlags parameter set to 
TA_UPDATECP. When this flag is set, Windows ignores the xPosStart and yPos- 
Start parameters on subsequent calls to the TabbedTextOut function, using the 
current position instead. 


The following example expands tabs trom the same x-coordinate as the string’s 
Starting point: 


LPSTR IpszTabbedText = "Column 1\tColumn 2\tTest of TabbedTextOut"; 
int aTabs[2] = { 150, 300 }; | 

int iStartXPos 100; 

int iStartYPos 100; 
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TabbedTextOut(hdc, /* handle of device context * / 


iStartXPos, iStartYPos, /* starting coordinates 2 / 

IpszTabbedText, /* address of text * / 

Tstrlen(|lpszTabbedText), /* number of characters * / 

sizeof(aTabs) / sizeof(int), /* number of tabs in array * / 

alabs, /* array for tab positions * / 

iStartXPos); /* x-coord. for tab expanding */ 
See Also — GetTabbedTextExtent, SetTextAlign, SetTextColor, TextOut 


TaskFindHandle Fu 


#include <toolhelp.h> 


BOOL TaskFindHandle(/pte, ie, 
TASKENTRY FAR* Ipte; /* address of TASKENTRY structure a 
HTASK htask; : /* handle of task 6 


The TaskFindHandle function fills the specified structure with information that 
describes the given task. 


Parameters [pte 
Points to a TASKENTRY structure to receive information about the task. The 
TASKENTRY structure has the following form: 


#Finclude <toolhelp.h> 


typedef struct tagTASKENTRY { /* te */ 


DWORD dwSize; 
HTASK hTask;. 
HTASK hTaskParent; 


HINSTANCE hInst; 
HMODULE hModule; 


WORD wSS; 

WORD wSP; 

WORD wStackTop; 

WORD wStackMinimum;, 

WORD wStackBottom; 

WORD wcEvents; 

HGLOBAL  hQueue; 

char szModule[MAX_MODULE_NAME + 1]; 
WORD wPSPOffset; 


HANDLE hNext; 
y TASKENTRY ; 
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Return Value 


Comments 


See Also 


TaskFirst 


For a full description of this structure, see the Microsoft Windows Program- 
mer’ s Reference, Volume 3. 


htask 
Identifies the task to be described. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The TaskFindHandle function can be used to begin a walk through the task 
queue. An application can examine subsequent entries in the task queue by using 
the TaskNext function. 


Before calling TaskFindHandle, an application must initialize the 


_ TASKENTRY structure and specify its size, in bytes, in the dwSize member. 


TaskFirst, TaskNext 


#include <toolhelp.h> 


BOOL TaskFirst(/pte) 
TASKENTRY FAR? /pte; /* address of TASKENTRY structure */ 


Parameters 


The TaskFirst function fills the specified structure with information about the 
first task on the task queue. 


lpte 
Points toa TASKENTRY structure to receive information about the first task. 
The TASKENTRY structure has the following form: 


#Hinclude eee heipino 


typedef struct tagTASKENTRY { /* te */ 


DWORD dwSize; 

HTASK hTask; 

HTASK hTaskParent; 
HINSTANCE hInst; 

ee Ae ea mnouu wos 

WORD — wSS; 

WORD wSP; 

WORD wStackTop; 
WORD ~ wStackMinimum; 
WORD wStackBottom; 


WORD wcEvents; 


Return Value 


Comments 


See Also 


TaskGetCSIP 
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HGLOBAL hQueue; 
char szModule[MAX_MODULE_NAME + 1]; 
WORD wPSPOffset; 
HANDLE hNext; 
} TASKENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s | Reference, Volume 3. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


The TaskFirst function can be used to begin a walk through the task queue. An ap- 
plication can examine subsequent entries in the task queue by using the TaskNext 
function. 


Before calling TaskFirst, an application must initialize the TASKENTRY struc- | 
ture and specify its size, in bytes, in the dwSize member. 


TaskFindHandle, TaskNext 


: #include <toolhelp.h> 
DWORD TaskGetCSIP(htask) 


HTASK htask; 


Parameters 


Return Value 


Comments 


See Also 


/* handle of task **/ 


The TaskGetCSIP function returns the next CS:IP value of a sleeping task. This 
function is useful for applications that must “know” where a sleeping task will 
begin execution upon awakening. . | 


htask 
Identifies the task whose CS:IP value is being examined. This task must be. 
sleeping when the application calls TaskGetCSIP. 


The return value is the next CS:IP value, if the function is successful. If the htask | 
parameter is invalid, the return value is NULL. 


TaskGetCSIP should not be called if htask identifies the current task. 


Directed Yield, TaskSetCSIP, TaskSwitch 
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TaskNext a faa] 


#include <toolhelp.h> 


BOOL TaskNext(Ipte) 
TASKENTRY FAR * Ipte; /* address of TASKENTRY structure */ 


The TaskNext function fills the specified structure with information about the 
next task on the task queue. 


Parameters lpte 
Points to a TASKENTRY structure to receive information about the next task. 
The TASKENTRY structure has the following form: | 


; | fHinclude <toolhelp.h> 


typedef struct tagTASKENTRY { /* te */ 
DWORD dwSize; 
HTASK hTask; 
HTASK hTaskParent; 
HINSTANCE hInst; 
HMODULE hModule; 


WORD wSS; 

WORD wSP; 

WORD wStackTop; 

WORD wStackMinimum; 

WORD  ~—~wStackBottom; 

WORD wcEvents; 

HGLOBAL hQueue; | ; 

char _ §zModuleLMAX_MODULE_NAME + 1]; 
WORD wPSPOffset; 


HANDLE hNext; 
} TASKENTRY; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. | 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments The TaskNext function can be used to continue a walk through the task queue. 
_ The walk must have been started by the TaskFirst or TaskFindHandle function. 


See Aiso VaskFindHandle, ‘laskFirst 
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TaskSetCSIP- aa] 


#include <toolhelp.h> 

DWORD TaskSetCSIP(htask, wCS, wIP) 
HTASK hitask; /* handle of task **/ 
WORD wCs; _—_—s /* value in CS register sa 
WORD wiIP; _/* value in IP register **/ 


The TaskSetCSIP function sets the CS:IP value of a sleeping task. When the task 
is yielded to, it will begin execution at the specified address. 


Parameters _ htask 
Identifies the task to be assigned the new CS:IP value. 


wCS | 
Contains the new value of the CS register. 


wIP 
Contains the new value of the IP register. 


Return Value The r return value is the previous CS:IP value for the task. The TaskSwitch func- 
tion uses this value. The return value is NULL if the htask parameter is invalid. 


Comments TaskSetCSIP should not be called if htask identifies the current ek. 


See Also DirectedYield. TaskGetCSIP, TaskSwitch 


TaskSwitch — Ba] 


#include <toolhelp.h> 
BOOL TaskSwitch(htask, dwNewCSIP) 
~HTASK htask; _-« /*® handle of task */ 


DWORD dwNewCsIP; /* execution address within task */ 
The TaskSwitch function switches to the given task. The task begins executing at 


the specified address. 


Parameters htask | 
Identifies the new task. 


940 = TerminateApp 


dwNewCSIP | : 
Identifies the address within the given task at which to begin execution. Be very 
careful that this address is not in a code segment owned by the given task. 


Return Value ‘The return value is nonzero if the task switch is successful. Otherwise, it is zero. 
Comments When the task identified by the htask parameter yields, TaskSwitch returns to the | 
calling application. 


TaskSwitch changes the CS:IP value of the task’s stack frame to the value 
specified by the dwNewCSIP parameter and then calls the Directed Yield function. 


See Also DirectedYield, TaskSetCSIP, TaskGetCSIP 


TerminateApp [3.1] 


#include <toolhelp.h> 

void TerminateA pp(htask, wFlags) 

HTASK htask; /* handle of task */ 
WORD wFlags; /* termination flags */ 


The TerminateA pp function ends the given application instance (task). 


Parameters htask 


Identifies the task to be ended. If this parameter is NULL, it identifies the cur- 
rent task. 

wFlags 
Indicates how to end the task. This parameter can be one of the following 
values: 
Value Meaning 
UAE_BOX Calls the Windows kernel to display the Application Error mes- 


sage box and then ends the task. 


NO_UAE_ BOX __ Calls the Windows kernel to.end the task but does not display 
the Application Error message box. The application’s interrupt 
Of HOUTICaLION Callback function siuuid Lave displayed an error 
message, a warning, or both. ; 


ReturnValue §—‘ This function returns only if htask is not NULL and does not identify the current 
: task. 


|g 


Comments 


See Also 


TextOut 
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The TerminateApp function unregisters all callback functions registered with the 
Tool Help functions and then ends the application as if the given task had pro- 
duced a general-protection (GP) fault or other error. 


TerminateApp should be used only by debugging applications, because the func- 
tion may not free not all objects owned by the ended application. 


InterruptRegister, InterruptUnRegister, NotifyRegister, NotifyUnRegister 


[2x] 


BOOL TextOut(hdc, nXStart, nYStart, IpszString, cbString) 


HDC hdc; 

int nXStart; 

int nYStart; 
LPCSTR IpszString; 
int cbString; 


Parameters 


Return Value 


Comments 


/* handle of device context sa 
/* x-coordinate of starting position a 
/* y-coordinate of starting position i 
/* address of string ‘a 
/* number of bytes in string */ 


The TextOut function writes a character string at the specified location, using the 
currently selected font. re 


hdc | 
Identifies the device context. — 


nX Start | | 
Specifies the logical x-coordinate of the starting point of the string. 


nYStart 

Specifies the logical y-coordinate of the starting point of the string. 
IpszString , | 

Points to the character string to be drawn. 


cbString 
Specifies the number of bytes in the string. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


~ 


Character origins are at the upper-left corner of the character cell. 


By default, the TextOut function does not use or update the current position. If an 
application must update the current position when calling TextOut, it can call the 
SetTextAlign function with the wFlags parameter set to TA_UPDATECP. When 


this flag is set, Windows ignores the nXStart and nYStart parameters on sub- 


sequent calls to the TextOut function, using the current position instead. 
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Example The following example uses the GetTextF ace function to retrieve the face name 
| of the current font, calls SetTextAlign so that the current position is updated when 
the TextOut function is called, and then writes some introductory text and the 
face name by calling TextOut: 


int nFaceNameLen; 
char aFaceName[80]; 


nFaceNameLen = GetTextFace(hdc, /* returns length of string */ 
sizeof(aFaceName), /* size of face-name buffer * / 
(LPSTR) aFaceName); /* address of face-name buffer */ 


SetTextAlign(hdc, 


TA_UPDATECP);  - /* updates current position * / 
MoveTo(hdc, 100, 100); /* sets current position * / 
TextOut(hdc, 0, @, /* uses current position for text */ 


"This is the current face name: ", 31); 
TextOut(hdc, 0, 8, aFaceName, nFaceNameLen); 


~ See Also ExtTextOut, GetTextExtent, SetTextAlign, SetTextColor, TabbedTextOut 


Throw | Ea 


void Throw(/pCatchBuf, nErrorReturn) 
const int FAR* [pCatchBuf; /* address of CATCHBUF saved by Catch */ 
int nErrorReturn; /* value to return from Catch function */ 


The Throw function restores the execution environment to the values saved in the 
specified array. Execution then transfers to the Catch function that copied the en- 
vironment to the array. | 


Parameters — [pCatchBuf 
Points toa CATCHBUF array that contains the execution environment. This 
array must have been set by a previous call to the Catch function. 


nErrorReturn | , 
Specifies the value to be returned to the Catch function. The meaning of the 
value is determined by the application. The value should be nonzero, so that the 
call to the Catch function can distinguish between a return from Catch (which 
returns zero) and a return from Throw. 


Return Value — This function does not return a value. | 


Comments _ _ The Throw function is similar to the C run-time function longjmp. 
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The function that calls Catch must free any resources allocated between the time | 
Catch was called and the time Throw was called. 


Do not use the Throw function across messages. For example, if an application 
calls Catch while processing a WM_CREATE message and then calls Throw 
while processing a WM_PAINT message, the application will terminate. 


Example — The following example calls the Catch function to save the current execution en- 
vironment before calling a recursive sort function. The first return from Catch is 
zero. If the doSort function calls the Throw function, execution will again return 
to the Catch function. This time, Catch returns the STACKOVERFLOW error 
passed by the doSort function. The doSort function is recursive—that is, it calls it- 
self. It maintains a variable, wStackCheck, that is used to check the amount of 
stack space used. If more than 3K of the stack has been used, doSort calls Throw 
to drop out of all the nested function calls back into the function that called Catch. 


dtdefine STACKOVERFLOW 1 


-UINT uStackCheck; 
CATCHBUF catchbuf; 


{ 
int iReturn; 
char szBuf[80]; 
if ((iReturn = Catch((int FAR*) catchbuf)) != @) { 
. /* Error processing goes here. */ 
43 
else { 
uStackCheck = Q; /* initializes stack-usage count */ 
doSort(1, 100); /* calls sorting function | * / 
} 
break; 
} 
void doSort(int sLeft, int sRight) 
{ : 
int sLast; 
* Determine whether more than 3K of the stack has been 
* used, and if so, call Throw to drop back into the 
* Original calling application. 
* 
* The stack is incremented by the size of the two parameters, — 
* the two local variables, and the return value (2 for a near 
* function call). | 
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 uStackCheck += (sizeof(int) * 4) + 2; 


if (uStackCheck > (3 * 1024)) 
Throw( (int FAR*) catchbuf, STACKOVERFLOW) ; 


. /* A sorting algorithm goes here. */ 


doSort(sLeft, sLast - 1);  /* note recursive call * / 
uStackCheck -= 10; /* updates stack-check variable */ 
} 
See Also - Catch 


TimerCount Ea 


#include <toolhelp.h> 


BOOL TimerCount(/pti) 
TIMERINFO FAR* [pti; /* address of structure for execution times +] 


The TimerCount function fills the specified structure with the execution times of 
the current task and VM (virtual machine). 


Parameters [pti 
Points to the TIMERINFO structure that will receive the execution times. The 
TIMERINFO structure has the following form: 


#Hinclude <toolhelp.h> 


typedef struct tagTIMERINFO { /* ti */ 
DWORD dwSize; 
DWORD dwmsSinceStart; 
DWORD dwmsThisVM; 

} TIMERINFO; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The TimerCount function provides a consistent source of timing information, ac- 


curate to the millisecond. In enhanced mode, TimerCount uses the VTD (virtual 
timer device) to obtain accurate execution times. — 


See Also 


TimerProc 
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In standard mode, TimerCount calls the GetTickCount function, which returns 
information accurate to one clock tick (approximately 55 ms). TimerCount then 
reads the hardware timer to estimate how many milliseconds remain until the next 
clock tick. The resulting time is accurate to 1 ms. 


Before calling TimerCount, an application must initialize the TIMERINFO 
structure and specify its size, in bytes, in the dwSize member. 


GetTickCount 


void CALLBACK TimerProe(hwnd, msg, idTimer, dwTime) 


HWND hwnd; 
UINT msg; 

UINT idTimer; 
DWORD dwTime; 


Parameters. 


Return Value 


Comments | 


‘See Also” 


/* handle of window for timer messages */ 
/** WM_TIMER message | “h 
/* timer identifier | *), 
/* current system time */ 


The TimerProc function is an application-defined callback function that processes 
WM_TIMER messages. 


hwnd 
Identifies the window associated with the timer. 


msg 
Specifies the WM_TIMER message. 


_ idTimer 


Specifies the timer’s identifier. 


dwTime 
Specifies the current system time. 


This function does not return a value. 
TimerProc is a placeholder for the application-defined function name. The actual 
name must be exported by including it in an EXPORTS statement in the applica- 


tion’s module-definition file. 


KillTimer, SetTimer 
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ToAscil 


int ToAscii(uVirtKey, uScanCode, lpbKeyState, lpdwTransKey, fuState) 


UINT wVirtKey; /* virtual-key code | 

UINT uScanCode; /* scan code ‘af 

BYTE FAR* l[pbKeyState; _ /* address of key-state array i | 

DWORD FAR®* [pdwTransKey; /* 32-bit buffer for translated key | 

UINT fuState; /* active-menu flag i 
The ToAscii function translates the specified virtual-key code and keyboard state 
to the corresponding Windows character or characters. 

Parameters uVirtKey 


Return Value 


| Comments 


Specifies the virtual-key code to be translated. 


uScanCode 
Specifies the hardware scan code of the key to be translated. The high-order bit 
_ of this value is set if the key is not pressed (is up). 


lpbKeyState 
Points to a 256-byte array that contains the current keyboard state. Each ele- 
ment (byte) in the array contains the state of one Key. If i high-order bit of a 
byte is set, the key 1 is pressed (is down). 


lpdwTransKey 
Points to a doubleword buffer to receive the translated Windows character or 
characters. 


SuState 
Specifies whether a menu is active. This parameter must be 1 if a menu is ac- 
tive, or zero otherwise. 


The return value is a negative value if the specified key is a dead key. Otherwise, 
it is one of the following values: 


Value Meaning | 

2 Two characters were copied to the buffer. This is usually an accent and a 
dead-key character, when the dead key cannot be translated otherwise. 

1 One Windows character was copied to the buffer. 

0 The specified virtual key has no translation for the current state of the key- 


board. 


If a previous dead key is stored in the keyboard driver, the parameters supplied to 
the ToAscii function might not be sufficient to translate the virtual-key code. 
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Typically, ToAscii performs the translation based on the virtual-key code. In some 
cases, however, the uScanCode parameter may be used to distinguish between a | 

key press and a key release. The scan code is used for translating ALT+number key 

combinations. 


See Also OemKeyScan, VkKeyScan 


TrackPopupMenu | / fo 


BOOL TrackPopupMenu(hmenu, fuF lags, x, y, nReserved, hwnd, Iprc) 


HMENU hmenu; /* handle of menu ae 
UINT fuFlags; /* screen-position and mouse-button flags ae 
int x; /* horizontal screen position | is 
int y; /* vertical screen position 7 oy 
int nReserved; /* reserved _ | 
HWND hwnd; /* handle of owner window | a 
const RECT FAR* (prc; /* address of structure with rectangle | 


The TrackPopupMenu function displays the given floating pop-up menu at the 
specified location and tracks the selection of items on the pop-up menu. A floating 
pop-up menu can appear anywhere on the screen. 


Parameters hmenu . 

Identifies the pop-up menu to Be displayed. The application retrieves this 
handle by calling the CreatePopupMenu function to create anew pop-up 
menu or by calling the GetSubMenu function to retrieve the handle of a pop- 
up menu associated with an existing menu item. 


fuFlags 
Specifies the screen-position and mouse-button flags. The screen-position mee 
_ can be one of the following: | 


Value | Meaning 


TPM_CENTERALIGN Centers the pop-up menu horizontally relative to the 
| coordinate specified by the x parameter. 


TPM_LEFTALIGN _ Positions the pop-up menu so that its left side is aligned 
: with the coordinate specified by the x parameter. 7 
TPM_RIGHTALIGN ___ Positions the pop-up menu so that its right side is — 


aligned with the coordinate specified by the x parameter. 
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The mouse-button flag can be one of the following: — 
Value Meaning a 


TPM_LEFTBUTTON Causes the pop-up menu to track the left mouse button. 


TPM_RIGHTBUTTON Causes the pop-up menu to track the right mouse but- 
ton instead of the left. 


Specifies the horizontal position, in screen coordinates, of the pop-up menu. De- 
pending on the value of the fuFlags parameter, the menu can be left-aligned, 
right-aligned, or centered relative to this position. 


Specifies the vertical position, in screen coordinates, of the top of the menu on 
the screen. 


nReserved 


Reserved; must be zero. 


hwnd 


Identifies the window that owns the pop-up menu. This window receives all 
WM_COMMAND messages from the menu. The window will not receive 
WM_COMMAND messages until TrackPopupMenu returns. 


pre 


Points to a RECT structure that contains the screen coordinates of a rectangle 
in which the user can click without dismissing the pop-up menu. If this parame- 
ter is NULL, the pop-up menu is dismissed if the user clicks outside the pop-up 
menu. The RECT structure has the following form: 


typedef struct tagRECT { /* reo */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Example — The following example creates and tracks a pop-up menu when the user clicks the 


matan 


Tate wn Liwwtt rare 
LULL LLIVUDSU UVULLULL. 


POINT ptCurrent; 
HMENU hmenu; 


ptCurrent = MAKEPOINT(1Param) ; 
hmenu = CreatePopupMenu() ; 
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AppendMenu(hmenu, MF_ENABLED, IDM_ELLIPSE, “Ellipse™); 

AppendMenu(hmenu, MF_ENABLED, IDM_SQUARE, "Square"™); 

AppendMenu(hmenu, MF_ENABLED, IDM_TRIANGLE, "Triangle™); 

ClientToScreen(hwnd, &ptCurrent); 

TrackPopupMenu(hmenu, TPM_LEFTALIGN, ptCurrent.x, 
ptCurrent.y, @, hwnd, NULL); 


See Also ~ CreatePopupMenu, GetSubMenu 
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int TranslateAccelerator(hwnd, haccl, Ipmsg) 


HWND hwnd; /* handle of window */ 
HACCEL haccl; /* handle of accelerator table af 
MSG FAR* /pmsg; /* address of structure with message information sa | 


The TranslateAccelerator function processes accelerator keys for menu com- 
mands. The function translates WM_KEYUP and WM_KEYDOWN messages to 
WM_COMMAND or WM_SYSCOMMAND messages if there is an entry for the 
accelerator key in the application’s accelerator table. 


Parameters ~ hwnd 
Identifies the window whose messages are to be translated. 


haccl 
Identifies an accelerator table (loaded by using ithe LoadAccelerators function). 


lpmsg 
Points to an MSG structure retrieved by acall to the GetMessage or Peek- 
Message function. The structure contains message information from the appli- 


cation’s message queue. The MSG structure has the following form: 


_ typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; | 
LPARAM 1Param; 


DWORD time; 
~ POINT pt; 
5 MSG; 


For a full description of this structure, see the M om Windows Program- 
mer’ s Reference, Volume 3. 


Return Value The return value is nonzero if the message is translated. Otherwise, it is zero. 
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Comments | The high-order word of the /Param parameter of the WM_COMMAND or 
WM_SYSCOMMAND message contains the value 1, to differentiate the message 
from messages sent by menus or controls. 


WM_COMMAND or WM_SYSCOMMAND messages are sent directly to the 
window, rather than being posted to the application queue. The Translate- 
Accelerator function does not return until the message is processed. . 


Accelerator keystrokes that are defined to select items from the System menu are 
translated into WM_SYSCOMMAND messages; all other accelerator keystrokes 
are translated into WM_COMMAND messages. 


When TranslateAccelerator returns a nonzero value (meaning that the message is 
translated), the application should not process the message again by using the 
TranslateMessage function. 


Keystrokes in accelerator tables need not correspond to menu items. 


If the accelerator keystroke does correspond to a menu item, the application is sent 
WM_INITMENU and WM_INITMENUPOPUP messages, just as if the user were 
trying to display the menu. However, these messages are not sent if any of the fol- 

lowing conditions are present: 


= The window is disabled. 
= The menu item is disabled. 


= The accelerator keystroke does not correspond to an item on the System menu 
and the window is minimized. 


= A mouse capture is in effect (for more information, see the description of the 
SetCapture function). 


If the window is the active window and there is no keyboard focus (generally the 
case if the window is minimized), WM_SYSKEYUP and WM_SYSKEYDOWN 
messages are translated instead of WM_KEYUP and WM_KEYDOWN messages. 


If an accelerator keystroke that corresponds to a menu item occurs when the win- 
dow that owns the menu is minimized, no WM_COMMAND message is sent. 
However, if an accelerator keystroke that does not match any of the items on the 
window’s menu or the System menu occurs, a WM_COMMAND message is sent, 
even if the window is minimized. 


Sea Alen GetMeccace LoadAcceleratars Peek Message, SetCantnre 
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TranslateMDISysAccel a 


BOOL TranslateMDISysAccel(hwndClient, lpmsg) 
HWND hwndClient; —_—s/* handle of parent MDI client window **/ 
MSG FAR® Ipmsg; /* address of structure with message data — 


The TranslateMDISysAccel function processes accelerator keystrokes for the 
given multiple document interface (MDI) child window. The function translates 
WM_KEYUP and WM_KEYDOWN messages to WM_SYSCOMMAND mes- 


sages. 


Parameters hwndClient 
Identifies the parent MDI client window. 


lpmsg 
Points to an MSG structure retrieved by a call to the GetMessage or Peek- 
Message function. The structure contains message information from the appli- 
cation’s message queue. The MSG structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; | 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 

} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


~ Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments — The high-order word of the /Param parameter of the WM_SYSCOMMAND mes- 
sage contains the value 1, to differentiate the message from messages sent by 


menus or controls. 


See Also GetMessage, PeekMessage 
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TranslateMessage 4s [ax 


- BOOL TranslateMessage(/pmsg) 7 
const MSG FAR* Ipmsg; /* address of MSG structure 3 


The TranslateMessage function translates virtual-key messages into character 
messages, as follows: 


# WM_KEYDOWN/WM_KEYUP combinations produce a WM_CHAR or 
WM_DEADCHAR message. 


#» WM_SYSKEYDOWN/WM_SYSKEYUP combinations produce a 
WM_SYSCHAR or WM_SYSDEADCHAR message. 


The character messages are posted to the application’s message queue, to be read 
the next time the application calls the GetMessage or PeekMessage function. 


Parameters — Ipmsg 
Points to an MSG structure retrieved by a call to the GetMessage or Peek- 
Message function. The structure contains message information from the appli- 
cation’s message queue. The MSG structure has the following form: 


typedef struct tagMSG { /* msg */ 
HWND hwnd; 
UINT message; 
WPARAM wParam; 
LPARAM 1Param; 
DWORD time; 
POINT pt; 
} MSG; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value _ The return value is nonzero if the message is WM_KEYDOWN, WM_KEYUP, 
WM_SYSKEYDOWN, or WM_SYSKEYUP, regardless of whether the key that 
was pressed or released meer a WM_CHAR message. Otherwise, the return 

- value is zero. 


Comments The TranslateMessage function does not modify the message pointed to by the | 
[pmsg parameter. | 


TranslateMessage produces WM_CHAR messages only for keys that are mapped 
_ to ASCII characters by the keyboard driver. 


An application should not call TranslateMessage if the application processes 
virtual-key messages for some other purpose. For instance, an application should 
not call TranslateMessage if the TranslateAccelerator function returns nonzero. 
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See Also _ GetMessage, PeekMessage, TranslateAccelerator 
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int TransmitCommChar(idComDev, chTransmit) 
int idComDeyv; /* communications device i 
char chTransmit; /* character to transmit = / 


The TransmitCommChar function places the specified character at the head of 
the transmission queue for the specified device. 


Parameters = idComDev 


Specifies the communications device to transmit the character. The Open- 
Comm function returns this value. 


chTransmit 
Specifies the character to be transmitted. 


- Return Value The return value is zero if the function is successful. It is less than zero if the char- 
acter cannot be transmitted. 


Comments The TransmitCommChar function cannot be called repeatedly if the device is 

| | not transmitting. Once TransmitCommChar places a character in the transmis- 
sion queue, the character must be transmitted before the function can be called 
again. TransmitCommChar returns an error if the previous character has not yet 
been sent. : 


Example The following example uses s the TransmitCommChar function to send characiers 
| from the keyboard to the communications port: 


case WM_CHAR: 


ch = (char)wParam; 
 TransmitCommChar(idComDev, ch); 


_/* Add a linefeed for every carriage return. */ 


if (ch == 0x@d) 
TrangmitcouncharCrdCombey. @x0a); 


break; 


See Also OpenComm, WriteComm 
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UnAllocDiskSpace 7 ra] 
#include <stress.h> 


void UnAllocDiskSpace(drive) 
UINT drive; 


The UnAllocDiskSpace function deletes the STRESS.EAT file from the root 
directory of the specified drive. This frees the disk space previously consumed by 
the AllocDiskSpace function. 


Parameters drive 
Specifies the disk partition on which to delete the STRESS.EAT file. This can 
be one of the following values: 


Value Meaning 


EDS_WIN Deletes the file on the Windows partition. 
EDS_CUR Deletes the file on the current partition. 
EDS_TEMP Deletes the file on the partition that contains the TEMP directory. 


Return Value This function does not return a value. 


See Also AllocDiskSpace 
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#include <stress.h> 
void UnAllocFileHandles(void) 
The UnAllocFileHandles enetion frees all file handles allocated by the AllocFile- 


Handles function. 
Parameters This function has no parameters. 
PD adesum Valin L.. AA awn a nt al. 
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See Also _ AllocFileHandles 
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UndeleteFile 


#include <wfext.h> 


int FAR PASCAL UndeleteFile(hwndParent, IpszDir) 
HWND hwndParent; /* handle of File Manager window ja 
LPSTR [pszDir; /* address of name of initial directory */ 


| The UndeleteFile function is an application-defined callback function that File 
Manager calls when the user chooses the Undelete command from the File 
Manager File menu. 


Parameters hwndParent | 
Identifies the File Manager window. An “undelete” dynamic-link library (DLL) 
should use this handle to specify the parent window for any dialog box or mes- 
sage box the DLL may display. 
lpszDir 
Points to a null-terminated string that contains the name of the initial directory. 


Return Value The retum value is one of the following, if the function is successful: 
Value Meaning 
on An error occurred. | 
IDOK A file was undeleted. File Manager will repaint its windows. 


IDCANCEL No file was undeleted. 


UngetCommChar a | | fax | 


int UngetCommChar(idComDev, chUnget) 
int idComDev; /* communications device **/ 
char chUnget; /* character to place in queue */ 


The UngetCommChar function places the specified character back in the receiv- 
ing queue. The next read operation will return this character first. 


Parameters — idComDev | : | | | 
Specifies the communications device that will receive the character. The Open- 
- Comm function returns this value. | 


chUnget | 3 | | 
Specifies the character to be placed in the receiving queue. 
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Return Value The return value is zero if the function is successful. Otherwise, it is less than zero. 


Comments Consecutive calls to the UngetCommChar function are not permitted. The charac- 
ter placed in the queue must be read before this function can be called again. 
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BOOL Unhook WindowsHook(idHook, hkprc) 
int idHook; /* type of hook function to remove sa 
HOOKPROC hiprc; /* hook function procedure-instance address */ 


The Unhook WindowsHook function is obsolete but has been retained for back- 
ward compatibility with Windows versions 3.0 and earlier. Applications written 
for Windows version 3.1 should use the Unhook WindowsHookEx function. 


The Unhook WindowsHook function removes an application-defined hook func- 
tion from a chain of hook functions. A hook function processes events before they 
are sent to an application’s message loop in the WinMain function. 


Parameters idHook 
Specifies the type of function to be removed. This parameter can be one of the 
following values: 
Value Meaning | 
WH_CALLWNDPROC Removes a window-procedure filter. For more in- 
formation, see the description of the CallWnd- 
Proc callback function. 
WH_CBT Removes a computer-based training (CBT) filter. 
For more information, see the description of the 
CBTProc callback function. 
WH_DEBUG Removes a debugging filter. For more informa- 
| tion, see the description of the DebugProc call- 
back function. 4 ey 
WH_GETMESSAGE Removes a message filter. For more information, 
| see the description of the GetMsgProc callback 
function. 
WH_HARDWARE Removes a nonstandard hardware-message filter. 


For more information, see the description of the 
ees ~ HardwareProc callback function. 
WH_JOURNALPLAYBACK Removes a journaling playback filter. For more 
information, see the description of the Journal- 
PlaybackProc callback function. 
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Value : Meaning 


WH_JOURNALRECORD Removes a journaling record filter. For more in- 
formation, see the description of the Journal- 
RecordProc callback function. 


WH_KEYBOARD Removes a keyboard filter. For more informa- 
tion, see the description of the KeyboardProc 

| callback function. | 

WH_MOUSE Removes a mouse-message filter. For more infor- 


mation, see the description of the MouseProc 
callback function. 


WH_MSGFILTER Removes a message filter. For more information, 

— ' see the description of the MessageProc callback 
function. bi 

WH_SYSMSGFILTER Removes a system-wide message filter. For more 


information, see the description of the SysMsg- — 
Proc callback function. | 


hkprce 
Specifies the procedure-instance address of the application-defined filter func- 
tion to remove. 
Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 
Comments The Unhook WindowsHook function calls the hook chain, causing the hook func- 


tion to receive a negative value for the idHook parameter. The hook function must 
then call the DefHookProc function, which removes the hook function from the 
chain. 


See Also SetWindowsHook 
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BOOL UnhookWindowsHookEx(hook) 
HHOOK hhook; /* handle of hook function to remove */, 


The Unhook WindowsHookEx function removes an application-defined hook 
function from a chain of hook functions. A hook function processes events before 
they are sent to an application’s message loop in the WinMain function. 


Parameters _ hhook 
Identifies the hook function to be removed. This is the value returned by the 
SetWindowsHookEx function when the hook was installed. 
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Return Value The return value is nonzero if the function is successful. It is zero if the hook can- 
not be found. 


Comments The UnhookWindowsHookEx function must be used in combination with the 
Set WindowsHookEx function. 


Example The following example uses the UnhookWindowsHookEx function to remove a 
message filter that was used to provide context-sensitive help for a dialog box: 


DLGPROC lIpfnAboutProc; 
HOOKPROC IpfnFilterProc; 
HHOOK hhook; 


case IDM ABOUT: 
~ |pfnAboutProc = (DLGPROC) MakeProcInstance(About, hinst); 
lpfnFilterProc = (HOOKPROC) MakeProcInstance(FilterFunc, hinst); 
hhook = SetWindowsHookEx(WH_MSGFILTER, IpfnFilterProc, 
hinst, (HTASK) NULL); | 


DialogBox(hinst, "“AboutBox", hwnd, lpfnAboutProc); 
UnhookWindowsHookEx(hhook) ; 
FreeProcInstance((FARPROC) IpfnFilterProc); 
FreeProcInstance((FARPROC) IpfnAboutProc) ; 


break; 


See Also ~ CallNextHookEx, SetWindowsHookEx 
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BOOL UnionRect(/prcDst, IpreSrcl » [prcSrc2) 


RECT FAR® [prcDst; /* address of structure for union 7 | 
const RECT FAR® [prcSrc1; /* address of structure with 1st rect. *) 
const RECT FAR® [prcSrc2;_ ——s/* address of structure with 2nd rect. 1 


The UnionRect function creates the union of two rectangles. The union is the 
smallest rectangle that contains both source rectangles. 


Parameters ~ IpreDst — : 7 | 
| Points to a RECT structure to receive a rectangle containing the rectangles 
pointed to by the /prcSrcl and lprcSrc2 parameters. The RECT structure has 
the following form: | : | | | 


Kee o 
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typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


IpreSrcl 
Points to a RECT structure that contains the first source rectangle. 


lprcSrc2 
Points to a ARECT structure that contains the seodad source rectangle. 


Return Value The return value is nonzero if the function is successful—that is, if the IprcDst pa- 
| rameter contains a nonempty rectangle. It is zero if the rectangle is empty or an © 
error Occurs. 


Comments Windows ignores the dimensions of an empty Se a aaa 1S, a ccimiele that 
| has no height or no width. 


See Also InflateRect, IntersectRect, OffsetRect, SubtractRect 
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void UnlockSegment(uSegment) 
UINT uSegment; /* specifies segment to unlock st 


The UnlockSegment function unlocks the specified discardable memory segment. | 
The function decrements (decreases by one) the segment’s lock count. The seg- _ 
ment is completely unlocked and subject to discarding wen the lock count : 
reaches : Zero. 


Parameters | uSegment 
sie Specifies the segment address of the segment to be unlocked. If this parameter: | 
is —1, the UnlockSegment function unlocks the current data segment. 


Return Va lue —* The return value is the lock count for the segment, if the function is successful. 
This function returns its result in the CX register. When the CX register contains = 
zero, the segment is completely unlocked. . 
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The value returned when the function is called in C should be ignored, because the 
return value can be checked only in assembly language. 


Comments An application should not rely on the return value to determine the number of 
times it must subsequently call UnlockSegment for the segment. 


Other functions also can affect the lock count of a memory object. For a list of 
these functions, see the description of the GlobalFlags function. 


Each time an application calls LockSegment for a segment, it must eventually call 
UnlockSeg:nent for the segment. 


See Also GlobalFlags, LockSegment, UnlockData 
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BOOL UnrealizeObject(hgdiob/) 
HGDIOBJ hgdiobj; /* handle of brush or palette st 


The UnrealizeObject function resets the origin of a brush or resets a logical 
palette. If the hgdiobj parameter identifies a brush, UnrealizeObject directs the 
system to reset the origin of the brush the next time it is selected. If the hgdiobj pa- 
rameter identifies a logical palette, UnrealizeObject directs the system to realize 
the palette as though it had not previously been realized. The next time the applica- 
tion calls the RealizePalette function for the specified palette, the system 
completely remaps the logical palette to the system palette. 


Parameters hgdiobj | 
Identifies the object to be reset. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


~ Comments The UnrealizeObject function should not be used with stock objects. . 


The UnrealizeObject function must be called whenever a new brush origin is set 
(by using the SetBrushOrg function). 


A brush identified by the hgdiobj parameter must not be the currently selected 
brush of any device context. 


A palette identified by hgdiobj can be the currently selected palette of a devic 
context. | 


Example 


See Also 
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The following example uses the SetBrushOrg function to set the origin coordi- 
nates of the current brush to (3,5), uses the SelectObject function to remove that 
brush from the device context, uses the UnrealizeObject function to force the sys- 
tem to reset the origin of the specified brush, and then calls SelectObject again to 
select the brush into the device context with the new brush origin: 


HBRUSH hbr, hbrOld; 
SetBkMode(hdc, TRANSPARENT); 
hbr = CreateHatchBrush(HS CROSS, RGB(@, @, Q0)); 


UnrealizeObject(hbr) ; 

SetBrushOrg(hdc, @, 0); 

hbrOld = SelectObject(hdc, hbr); 

Rectangle(hdc, 0, 0, 200, 200); 

hbr = SelectObject(hdc, hbrOld); /* deselects hbr */ 
UnrealizeObject(hbr); /* resets origin next time hbr selected */ 
SetBrushOrg(hdc, 3, 5); - 
hbrOld = SelectObject(hdc, hbr); /* selects hbr again */ 
Rectangle(hdc, 0, 0, 200, 200); 


SelectObject(hdc, hbrOld); 
DeleteObject(hbr); 


RealizePalette, SelectObject, SetBrushOrg 
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BOOL UnregisterClass(/pszClassName, hinst) 
LPCSTR IpszClassName; /* address of class-name string ae 


: HINSTANCE hinst;. 


Parameters | 


/* handle of application instance 


The UnregisterClass function removes a window class, freeing the storage r¢ re- 
quired for the class. | 


[pszClassName 
Points to a null-terminated string containing the class name. This class name 
must have been registered by a previous call to the RegisterClass function with 
a valid hinstance member of the WNDCLASS structure. Predefined classes, 
such as dialog box controls, cannot be unre e The WNDCLASS struc- 
ture has the following form: 
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typedef struct tagWNDCLASS { /* we */ 


UINT style; 
WNDPROC IpfnWndProc; 
int cbClsExtra; 
int cbWndExtra; 
HINSTANCE hInstance; 
HICON hIcon; 


HCURSOR hCursor; 

HBRUSH hbrBackground; 

LPCSTR ]pszMenuName;. 

LPCSTR lTpszClassName; 
} WNDCLASS; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


hinst 
Identifies the instance of the module that created the class. 


Return Value The return value is nonzero if the function successful. It is zero if the class could 
~ not be found or if a window exists that was created with the class. 


Comments Before calling this function, an application should destroy all windows that were 
created with the specified class. 


See Also RegisterClass 
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int UpdateColors(hdc) 
HDC hdc; /* handle of device context */ 


The UpdateColors function updates the client area of the given device context by 
matching the current colors in the client area, pixel by pixel, to the system palette. 
An inactive window with a realized logical palette may call UpdateColors as an 
alternative to redrawing its client area when the system palette changes. 


Parameters hdc 


Identifies the device context. 


Return Value The return value is not used. 


Comments 
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Using UpdateColors to update a client area is typically faster than redrawing the 
area. However, because UpdateColors performs the color translation based on the 
color of each pixel before the system palette changed, each call to this function re- 
sults in the loss of some color accuracy. 


UpdateWindow [2x | 


_ void UpdateWindow(hwnd) 


HWND hwnd; 


Parameters 


Return Value 


See Also 


/* handle of window a | 


The UpdateWindow function updates the client area of the given window by 
sending a WM_PAINT message to the window if the update region for the win- 
dow is not empty. The function sends a WM_PAINT message directly to the win- 
dow procedure of the given window, bypassing the application queue. If the 
update region is empty, no message is sent. 


hwnd 
Identifies the window to be updated. 


This function anes not return a value. 


ExcludeUpdateRgn, GetUpdateRect, GetUpdateRgn, InvalidateRect, 
InvalidateRgn 
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void ValidateCodeSegments(void) 


Parameters 


Return Value 


The ValidateCodeSegments function tests all code segments for random memory 
overwrites. The function works only in real mode (for Windows versions earlier 
than 3.1) and only with the debugging version of Windows. 


This function has no parameters. 


This function does not return a value. 
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Comments Because code segments are not writable in protected mode (standard or enhanced), 
this function does nothing in Windows 3.1. 


See Also ValidateFreeSpaces 


ValidateFreeSpaces [ 2.x | 


void ValidateFreeS paces(void) 


The ValidateFreeSpaces function checks free segments in memory for valid con- 
tents. This function 1s available only in the debugging version of Windows. 


Parameters This function has no parameters. 
Return Value This function does not return a value. 
Comments - In the debugging version of Windows, the kernel fills all the bytes in free seg- 


ments with the hexadecimal value OxOCC. This function begins checking for valid 
contents in the free segment with the lowest address; it continues checking until it 
finds an invalid byte or until it has determined that all free space contains valid 
contents. Before calling this function, put the following lines in the WIN.INI file: 


[KERNEL] | 
EnableFreeChecking=1 
Enabl eHeapChecking=1 


Windows sends debugging information to the debugging terminal if an invalid | 
byte is encountered, and then it performs a fatal exit. 


The [KERNEL] entries in WIN.INI cause automatic checking of free memory. 
Before returning a memory object to the application in response to a call to the 
GlobalAlloc function, Windows checks that memory to make sure it is filled with 
OxOCC. Before a call to the GlobalCompact function, all free memory is checked. 
Note that using this function slows Windows system-wide by about twenty per- 
cent. 


See Also GlobalAlloc, GlobalCompact, ValidateCodeSegments 
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[ 2.x ] 


void ValidateRect(hwnd, Iprc) 


HWND hwnd; /* handle of window **/ 
const RECT FAR*® (prc; /* address of structure with validation rect. | 
The ValidateRect function validates the client area within the given rectangle by 
removing the rectangle from the update region of the given window. 
Parameters — hwnd 


Return Value 


Comments 


_ See Also 


Identifies the window whose update region is to be modified. 


lprc 
Points to a RECT structure that contains the client coordinates of the rectangle 
to be removed from the update region. If this parameter is NULL, the entire 
client area is removed. The RECT structure has the following form: 


typedef struct tagRECT { /* rc */ 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


This function does not return a value. 


The BeginPaint function automatically validates the entire client area. Neither the 
ValidateRect nor the ValidateRgn function should be called if a portion of the up- 
date region needs to be validated before the next WM_PAINT message is 
generated. 


Windows continues to generate WM_PAINT messages until the current update re- 
gion is validated. 


BeginPaint, InvalidateRect, InvalidateRgn, ValidateRgn 
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void ValidateRgn(hwnd, hrgn) 
HWND hwnd; /* handle of window — */ 
HRGN hrgn; /* handle of valid region *) 


The ValidateRgn function validates the client area within the given region by re- 
moving the region from the current update region of the Sr window. 


Parameters hwnd 
Identifies the window whose update region is to be modified. 


hrgn 
_ Identifies a region that defines the area to be removed from the update region. 
If this parameter is NULL, the entire client area is removed. 


Return Value This function does not return a value. 


Comments The given region must have been created by a region function. The region coordi- 
nates are assumed to be client coordinates. 


The BeginPaint function automatically validates the entire client area. Neither the 
ValidateRect nor the ValidateRgn function should be called if a portion of the up- 
date region must be validated before the next WM_PAINT message is generated. 


See Also BeginPaint, InvalidateRect, InvalidateRgn, ValidateRect 


VerFindFile © [34 | 
#include <ver.h> 


UINT VerFindFile(flags, lpszFilename, IpszWinDir, IpszAppDir, lpszCurDir, lpuCurDirLen, 
[pszDestDir, lpuDestDirLen) 


UINT flags; /* source-file flags */ 
LPCSTR IpszFilename; /* address of buffer for file i 
LPCSTR [pszWinDir; /* address of Windows directory *} 
TL DPCSTR etren tee Oa r ies addrece of annlication directory * / 
LPSTR [pszCurDir; /* address of buffer for current directory td 
UINT FAR* [puCurDirLen; —_—si/* address of buffer size for directory sd 
LPSTR /pszDestDir; — /* address of buffer for dest. directory | 


UINT FAR®* [puDestDirLen; /* address of size for dest. directory **/ 


Parameters 
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The VerFindFile function determines where to install a file based on whether it lo- 
cates another version of the file in the system. The values VerFindFile returns are 
used in a subsequent call to the VerInstallFile function. 


flags 
Contains a bitmask of flags. This parameles can be VFFF_ISSHAREDFILE, 
which indicates that the source file may be shared by multiple applications. 
VerFindFile uses this information to determine where the file should be 
copied. All other values are reserved for future use. 


lpszFilename 
Points to a null-terminated string specifying the name of the file to be installed. 
_ This name should include only the filename and extension, not a path. 


| lpszWinDir 


Points to a null-terminated string pecans the Windows directory. This string 
is returned by the GetWindowsDir function. The dynamic-link library (DLL) 
version of VerFindFile ignores this parameter. 


_ IpszAppDir 


Points to a null-terminated string specifying the drive letter and directory where — 
the installation program is installing a set of related files. If the installation pro- 
gram is installing an application, this is the directory where the application will 
reside. This directory will also be the meena s working directory unless | 
you specify otherwise. 


IpszCurDir 


Points to a buffer that receives the path to a current version of the file being in- 
stalled. The path is a null-terminated string. If a current version is not installed, 
the buffer will contain the source directory of the file being installed. The buff- 
er must be at least_MAX_PATH bytes long. 


lpuCurDirLen | 
Points to a null-terminated string specifying the length, in bytes, of the buffer 
pointed to by /pszCurDir. On return, [puCurDirLen contains the size, in bytes, 
of the data returned in /pszCurDir, including the terminating null character. If 
the buffer is too small to contain all the data, JpuCurDirLen will be greater than 
the actual size of the buffer. 


lpszDestDir | 
Points to a buffer that receives the path to the installation directory recom- 
mended by VerFindFile. The path is a null- terminated string. The buffer must 
be at least_MAX_PATH eee long. 


lpuDestDirLen 
Points to the length, in bytes, of the buffer pointed to by /pszDestDir. On return, 
_[puDestDirLen contains the size, in bytes, of the data returned in /pszDestDir, __ 
including the terminating null character. If the buffer is too small to contain all 
_ the data, JpuDestDirLen will be greater than the actual size of the buffer. 
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Return Value 


Comments 


See Also 


The return value is a bitmask that indicates the status of the file, if the function is 
successful. This value may be one or more of the following: 


Error Meaning 

VFF_CURNEDEST Indicates that the currently installed version of the file is 
not in the recommended destination. 

VFF_FILEINUSE Indicates that Windows is using the currently installed 
version of the file; therefore, the file cannot be overwrit- 
ten or deleted. 


VFF_BUFFTOOSMALL Indicates that at least one of the buffers was too small to 
contain the corresponding string. An application should 
check the [puCurDirLen and lpuDestDirLen parameters 
to determine which buffer was too small. 


All other values are reserved for future use. 


The dynamic-link library (DLL) version of VerFindFile searches for a copy of the 


_ specified file by using the OpenFile function. In the LIB version, the function 


searches for the file in the Windows directory, the system directory, and then the 
directories specified by the PATH environment variable. 


VerFindFile determines the system directory from the specified Windows 
directory, or it searches the path. 


If the flags parameter indicates that the file is private to this application (not 
VFFF_ISSHAREDFILE), VerFindFile recommends installing the file in the appli- 
cation’s directory. Otherwise, if the system is running a shared copy of Windows, 
the function recommends installing the file in the Windows directory. If the sys- 
tem is running a private copy of Windows, the function recommends installing the 
file in the system directory. 


VerInstallFile 


VerlnstallFile 


#include <ver.h> | 


VerinstallFile 
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[3.1] 


DWORD VerlnstallFile(/lags, lpszSrcFilename, IpszDestFilename, lpszSrcDir, lpszDestDir, 
lpszCurDir, lpszTmpFile, lpwTmpFileLen) 


UINT flags; /* source-file flags **/ 
LPCSTR /pszSrcFilename; /* address of source filename sa 
LPCSTR [pszDestFilename; /* address of destination filename */ 
LPCSTR IpszSrcDir; /* address of buffer for source dir. name a 
LPCSTR IpszDestDir; /* address of buffer for dest. dir. name ‘i 
LPCSTR /pszCurDir; /* address of buffer for preexisting dir. **/ 
LPSTR [pszTmpFile; /* address of buffer for temp. filename *), 
UINT FAR®* [pwTmpFileLen; /* address of buffer for temp. file size otk 


Parameters — 


The VerInstallFile function attempts to install a file based on information re- 
turned from the VerFindFile function. VerInstallFile decompresses the file with 
the el function and checks for errors, such as outdated files. 


fags 


Contains a bitmask of flags. This parameter can be a combination of the follow- 


ing values: 
Value 


VIFF_FORCEINSTALL 


: ’ Meaning — | 


Installs the file regardless of mismatched version 


numbers. The function will check only for physical 


~ errors during installation. 


If flags includes VIFF_FORCEINSTALL and 
lpszImpFileLen is not a pointer to zero, VerInstall- 


File will skip all version checks of the temporary 


VIFF_DONTDELETEOLD 


file and the destination file and rename the 
temporary file to the name specified by 
IpszSrcFilename, as long as the temporary file ex- 


ists in the destination directory, the destination file — 


is not in use, and the user has privileges to delete 
the destination file and rename the temporary file. 
The return value from VerInstallFile should be 
checked for any errors. 


Installs the file without deleting the previously in- 


stalled file, if the previously installed file is not in 
the destination directory. If the previously installed 
file is in the destination directory, VerInstallFile re- 


~ places it with the new file upon successful installa- 


tion. 


All other values are reserved for future use. 
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Return Value 


lpszSrcFilename 
Points to the name of the file to be installed. This is the filename in the 
directory pointed to by /pszSrcDir; the filename should include only the 
filename and extension, not a path. VerInstallFile opens the source file by 
using the LZOpenFile function. This means it can handle both files as 
specified and files that have been compressed and renamed by using the 
/r option with COMPRESS.EXE. 


[pszDestFilename 
Points to the name VerInstallFile will give the new file upon installation. This 
filename may be different than the filename in the directory pointed to by 
[pszSrcFilename. The new name should include only the filename and exten- 
- sion, not a path. | 


lpszSrcDir 
Points to a buffer that contains the directory name where the new file is found. 


lpszDestDir 
Points to a buffer that contains the directory name where the new file should be 
installed. The VerFindFile function returns this value in the IpszDestDir pa- 
rameter. 


[pszCurDir 
Points to a buffer that contains the directory name where the preexisting version 
of this file is found. VerFindFile returns this value in the JpszCurDir parame- 
ter. If the filename specified in /pszDestFilename already exists in the lpszCur- 
Dir directory and flags does not include VIFF_DONTDELETEOLD, the 
existing file will be deleted. If IpszCurDir is a pointer to NULL, a previous ver- 
sion of the file does not exist on the system. 


lpszTmpFile 
Points to a buffer that should be empty upon the initial call to VerInstallFile. 
The function fills the buffer with the name of a temporary copy of ace source 
file. The buffer must be at least_MAX_PATH bytes long. 


lpwTmpFileLen 
Points to the length of the buffer pointed to by /pszTmpFile. On return, 
IpwImpFileLen contains the size, in bytes, of the data returned in [pszTmpFile, 
including the terminating null character. If the buffer is too small to contain all 
the data, Jp>wTmpFileLen will be greater than the actual size of the buffer. 


If flags includes VIFF_FORCEINSTALL and lpwTmpFileLen is not a pointer 
to zero, VerInstallFile will rename the epee file to the name specified by 
IpszSrcFilename. 


The return value is a bitmask that indicates exceptions, if the function 1 1s SuCcess- 
ful. This value may be one or more of the LonOwAne: 


Value 


VIF_TEMPFILE 


VIF_MISMATCH 
VIF_SRCOLD 
VIF_DIFFLANG 


VIF_DIFFCODEPG 


VIF_DIFFTYPE 
VIF_WRITEPROT 


VIF_FILEINUSE 


VIF_OUTOFSPACE 


VIF_ACCESS VIOLATION 


-VIE_SHARINGVIOLATION ~ 


VIF_CANNOTCREATE 
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Meaning 


Indicates that the temporary copy of the new file is 


in the destination directory. The cause of failure is re- 
flected in other flags. Applications should always 
check whether this bit is set and delete the temporary 
file, if required. 

Indicates that the new and preexisting files differ in 
one or more attributes. This error can be overridden 
by calling VerInstallFile again with the 
VIFF_FORCEINSTALL flag. 


Indicates that the file to install is older than the | 


preexisting file. This error can be overridden by 
calling VerInstallFile again with the 


_ VIFF_FORCEINSTALL flag. 


Indicates that the new and preexisting files have 
different language or code-page values. This error 
can be overridden by calling VerInstallFile again 
with the VIFF_FORCEINSTALL flag. 


Indicates that the new file requires a code page that 
cannot be displayed by the currently running version 
of Windows. This error can be overridden by calling 
VerInstallFile with the VIFF_FORCEINSTALL 
flag. 

Indicates that the new file has a different type, sub- 
type, or operating system than the preexisting file. 
This error can be overridden by calling VerInstall- 
File again with the VIFF_FORCEINSTALL flag. 


Indicates that the preexisting file is write-protected. 
The installation program should reset the read-only 
bit in the destination file before proceeding with the — 
installation. | 


Indicates that the preexisting file is in use by Win- 
dows and cannot be deleted. , 


Indicates that the function cannot create the tem- 
porary file due to insufficient disk space on the desti- 


‘nation drive. 


Indicates that a create, delete, or rename operation 
failed due to an access violation. 


Indicates that a create, delete, or rename operation | 
failed due to a sharing violation. 
Indicates that the function cannot create the tem- 


porary file. The specific error may be described by 
another mae 
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Comments 


Value Meaning 


VIF_CANNOTDELETE Indicates that the function cannot delete the 
| _ destination file or cannot delete the existing ver- 
sion of the file located in another directory. If the 
VIF_TEMPFILE bit is set, the installation failed and 
the destination file probably cannot be deleted. 


VIF_CANNOTRENAME Indicates that the function cannot rename the tem- 
porary file but already deleted the destination file. 
VIF_OUTOFMEMORY Indicates that the function cannot complete the re- 


quested operation due to insufficient memory. Gener- 
ally, this means the application ran out of memory 
attempting to expand a compressed file. 


VIF_CANNOTREADSRC - Indicates that the function cannot read the source 
file. This could mean that the path was not specified 
properly, that the file does not exist, or that the file is 
a compressed file that has been corrupted. To distin- 
guish these conditions, use LZOpenFile to deter- 
mine whether the file exists. (Do not use the 
OpenFile function, because it does not correctly 
translate filenames of compressed files.) Note 
that VIF_CANNOTREADSRC does not cause 
either the VIF_ACCESSVIOLATION or 
VIF_SHARINGVIOLATION bit to be set. 

VIF_CANNOTREADDST Indicates that the function cannot read the destina- 
tion (existing) files. This prevents the function from 
examining the file’s attributes. 

VIF_BUFFTOOSMALL Indicates that the IpszTmpFile buffer was too small 

i to contain the name of the temporary source file. On 
return, [pwTmpFileLen contains the size of the buff- 
er required to hold the filename. 


All other values are reserved for future use. 


VerInstallFile is designed for use in an installation program. This function copies 


a file (specified by IpszSrcFilename) from the installation disk to a temporary file 
in the destination directory. If necessary, VerInstallFile expands the file by using 
the functions in LZEXPAND.DLL. 


Ifa preexisting copy of the file exists in the destination directory, VerInstallFile 
compares the version information of the temporary file to that of the preexisting 


fila If the nraayvictina file ic more recent than the new version, ar if the files’ at- 


AfwWe AL UAL iY * Wwf bi este: + 


tributes are significantly different, VerInstallFile returns one or more error 
values. For example, files with different languages would cause VerInstallFile to 
return VIF_DIFFLANG. 


VerInstallFile leaves the temporary file in the destination directory. If all of the er- 
rors are recoverable, the installation program can override them by calling Ver- 
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InstallFile again with the VIFF_FORCEINSTALL flag. In this case, 
IpszSrcFilename should point to the name of the temporary file. Then, VerInstall- 
File deletes the preexisting file and renames the temporary file to the name 
specified by IpszSrcFilename. If the VIF_TEMPFILE bit indicates that a tem- 
porary file exists and the application does not force the installation by using the 
VIFF_FORCEINSTALL flag, the application must delete the temporary file. 


If an installation program attempts to force installation after a nonrecoverable 
error, such as VIF_CANNOTREADSRC, VerInstallFile will not install the file. 


See Also — VerFindFile 


VerLanguageName Exe 


#include <ver.h> | 


UINT VerLanguageName(uLang, IpszLang, cbLang) 


UINT uLang; /* Microsoft language identifier Ef 
LPSTR /pszLang; /* address of buffer for language string sa 


UINT cbLang; /* size of buffer i 


The VerLanguageName function converts the specified binary Microsoft lan- 
guage identifier into a text representation of the language. 


Parameters ule 
- Specifies the binary Microsoft language identifier. For example, 
— VerLanguageName translates 0x040A into Castilian Spanish. If Ver- 
LanguageName does not recognize the identifier, the JpszLang parameter will 
point to a default string, such as “Unknown language”. For a complete list of 
the language identifiers supported by Windows, see the none Comments 
section. , 
lpszLang 
Points to the buffer to receive the null-terminated tring representing the lan- | 
- guage a by the uLang parameter. | | 


cbLang 
Indicates the size of the buffer, in bytes, pointed to by /pszLang. 


Return Value The return valtie is the length of the string that represents the language identifier, 
if the function is successful. This value does not include the null character at the 
end of the string. If this value is greater than cbLang, the string was truncated to 
cbLang. The return value is zero a an error occurs. Unknown uLang values do not 
produce errors. 
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Comments 


Typically, an installation application uses this function to translate a language iden- 
tifier returned by the VerQuery Value function. The text string may be used in a 


_ dialog box that asks the user how to proceed in the event of a language conflict. 


Windows supports the following language identifiers: 


Value Language 
0x0401 Arabic 
0x0402 Bulgarian 
0x0403 Catalan 
0x0404 Traditional Chinese 
0x0405 Czech 
0x0406 Danish 
0x0407 German 
0x0408 Greek 
0x0409 U.S. English 
0x040A Castilian Spanish 
0x040B Finnish | 
0x040C French 
0x040D Hebrew 
0x040E Hungarian 
Ox040F Icelandic 
0x0410 Italian 
0x0411 Japanese 
0x0412 Korean 
0x0413 Dutch 
0x0414 Norwegian — Bokmal 
0x0415  _—s— Polish 
~ 0x0416 Brazilian Portuguese 
-0x0417 Rhaeto-Romanic 
0x0418 Romanian 
0x0419 Russian 
Ox041A Croato-Serbian (Latin) 
0x041B Slovak a 
-0x041C Albanian 
0x041D Swedish 
Ox041E Thai 
—0x041F Turkish 
0x0420 = Urdu 
-0x0421 Bahasa 


Value 


0x0804 
0x0807 
0x0809 
Ox080A 
0x080C 
0x0810 
0x0813 
0x08 14 
0x0816 
Ox081A 
Ox0COC 
0x 100C 


‘VerQueryValue 


#include <ver.h> 


BOOL VerQueryValue(/pvBlock, IpszSubBlock, lplpBuffer, Ipcb) 
/* address of buffer for version resource 


const void FAR* /pvBlock; 
LPCSTR [pszSubBlock; 


VOID FAR* FAR® IplpBuffer; 
UINT FAR* [pcb; 


Parameters 


The VerQuery Value function returns selected version information from the 
specified version-information resource. To obtain the appropriate resource, the 


Language 


Simplified Chinese 
Swiss German 

U.K. English 
Mexican Spanish 
Belgian French 

Swiss Italian 

Belgian Dutch 
Norwegian — NBO 
Portuguese 
Serbo-Croatian (Cyrillic) 
Canadian French 
Swiss French 


/* address of value to retrieve 
_ /* address of buffer for version pointer 
/* address of buffer for version-value length 


VerQueryValue 


GetFileVersionInfo function must be called before VerQuery Value. 


lpvBlock 
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Points to the buffer containing thew version-information resource returned by the 
GetFileVersionInfo function. 


lpszSubBlock 
Points to a zero-terminated string specifying which version-information value 


to retrieve. The string consists of names separated by backslashes (\) and can 
have one of the following forms: 
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Return Value 


Comments. 


Form . Description 


\ | Specifies the root block. The func- 
tion retrieves a pointer to the 
VS_FIXEDFILEINEFO structure 
for the version-information resource. 


\VarFileInfo\Translation Specifies the translation table in the 
| variable information block. The 

function retrieves a pointer to an 
array of language and character-set 
identifiers. An application uses these 
identifiers to create the name of an 
language-specific block in the 
version-information resource. 


\StringFileInfo\lang-charset\string-name Specifies a value in a language- 
specific block. The lang-charset 
name is a concatenation of a lan- 
guage and character-set identifier 
pair found in the translation table 
for the resource. The lang-charset 
name must be specified as a hex- 
adecimal string. The string-name 
name is one of the predefined 
strings described in the following 
Comments section. 


lplpBuffer 
Points to a buffer that receives a pointer to the version-information value. 


lpcb 
Points to a buffer that receives the length, in bytes, of the version-information - 
value. 


The return value is nonzero if the specified block exists and version information 
is available. If [pcb is zero, no value is available for the specified version- 
information name. The return value is zero if the specified name does not 

exist or the resource pointed to by [pvBlock is not valid. 


The string-name in the lpszSubBlock sarees can be one - the TOP OwINS prede- 


fined names: 
Name | i _ Value 
Comments , Specifies additional information that should be displayed for 
- diagnostic purposes. 
CompanyName Specifies the company that produced the file—for example, 


“Microsoft Corporation” or “Standard Microsystems Corpora- 
tion, Inc.”. This string 1s required. 


Example 


Name 


FileDescription 


FileVersion 


InternalName 
LegalCopyright 


LegalTrademarks 


OriginalFilename 


PrivateBuild 


ProductName 
ProductVersion 


SpecialBuild 
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~ Value 


Specifies a file description to be presented to users. This string 
may be displayed in a list box when the user is choosing files 
to install—for example, “Keyboard Driver for AT-Style 
Keyboards” or “Microsoft Word for Windows”. This string is 


required. 


Specifies the version number of the file—for example, “3.10” 
or “5.00.RC2”. This string is required. 


Specifies the internal name of the file, if one exists—for ex- _ 
ample, a module name if the file is a dynamic-link library. If 
the file has no internal name, this string should be the original 
filename, without extension. This string is required. 


Specifies all copyright notices that apply to the file. This should 
include the full text of all notices, legal symbols, copyright 
dates, and so on—for example, “Copyright Microsoft 
Corporation 1990-1991”. This string is optional. 

Specifies all trademarks and registered trademarks that apply to 
the file. This should include the full text of all notices, legal 
symbols, trademark numbers, and so on—for example, 
“Windows(TM) is a trademark of Microsoft Corporation”. This 
string is optional. 


Specifies the original name of the file, not inclading a path. 


This information enables an application to determine whether a 


file has been renamed by a user. The format of the name de- 
pends on the file system for which the file was created. This 
string is required. 


Specifies information about a private version of the file—for 
example, “Built by TESTER1 on \TESTBED”. This string 
should be present only if the VS_FF_PRIVATEBUILD flagis _ 
set in the dwFileFlags member of the VS. FIXEDFILEINFO 
structure of the root block. 


Specifies the name of the product with which the file is dis- 
tributed—for example, “Microsoft Windows”. This ee is re- 
quired. 


Specifies the version of the erodtiet with which the file is dis- 
tributed—for example, “3.10” or “5.00.RC2”. This string is re- 
quired. 


Specifies how this version of the file differs from the standard 
version—for example, “Private build for TESTER1 solving 
mouse problems on M250 and M250E computers”. This string 
should be present only if the VS_FF_SPECIALBUILD flag is 
set in the dwFileFlags member of the VS_FIXEDFILEINFO 
structure in the root block. 


The following example loads the version information for a dynamic- link library 
and retrieves the company name: | 
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BYTE abData[512]; 
DWORD' handle; 
DWORD dwSize; 
LPBYTE 1pBuffer; 
char szName[512]; 


dwSize = GetFileVersionInfoSize("c:\\d11\\sample.d11", &handle)); 
GetFileVersionInfo("c:\\d11\\sample.dl1", handle, dwSize, abData)); 


VerQueryValue(abData, "\\VarFileInfo\\Translation", &lpBuffer, 
&dwSize)); 


if (dwSize!=0) { 
wsprintf(szName, "\\StringFileInfo\\%81x\\CompanyName", &lpBuffer);. 
~VerQueryValue(abData, szName, &lpBuffer, &dwSize); 

} | 


See Also — GetFileVersionInfo 


VkKeyScan [ 2.x | 


UINT VkKeyScan(uChar) | 
UINT uChar; /* character to translate a 


The VkKeyScan function translates a Windows character to the corresponding 
virtual-key code and shift state for the current keyboard. 


Parameters '  uChar ae | 
Specifies the character to be translated to a virtual-key code. 


Return Value The return value is the virtual-key code and shift state, if the function is success- 
- ful. The low-order byte contains the virtual-key code; the high-order byte contains 
the shift state, which can be one of the following: 


Value | Meaning 
1 - Character is shifted. 
ae Character is a control character. 
.35 Shift-key combination that is not used for characters. 
6 Character is generated by the CTRL+ALT key combination. 


7 Character is generated by the SHIFT+CTRL+ALT key combination. 


Comments 


| See Also 
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__ If no key is found that translates to the passed Windows ee the return value 


is —I. 


Translations for the numeric keypad (VK_NUMPADO0 through VK_DIVIDE) are 
ignored. This function is intended to force a translation for the main keyboard only. 


Applications that send characters by using the WM -KEYUP and 
WM_KEYDOWN messages use this function. 


OemKeyScan 


WaitMessage i La] 


void Heese ra) 


Parameters 


~ Return Value 


Comments 


- See Also 


The WaitMessage function yields control to other applications when an applica- | 
tion has no other tasks to perform. The WaitMessage function suspends the appli- 
cation and does not return until a new message is placed in the application’s queue. 


This function has no parameters. 
This function does not return a value. 


The WaitMessage function normally returns immediately if there is a message in 
the queue. If an application has used the PeekMessage function but not removed 
the message, however, WaitMessage does not return until the message is re- _ 
ceived. Applications that use the PeekMessage function should remove any | 
retrieved messages from the queue before calling WaitMessage. 


The GetMessage, PeekMessage, and WaitMessage functions yield control to 


| other applications. Using these functions is the only way to allow other applica- 
tions to run. Applications that do not call any of these functions for long periods 
_ prevent other applications from running. 


GetMessage, PeekMessage 


980 WaitSoundState 


WaitSoundState 


int WaitSoundState(/{nState) 


int fnState; 


WEP | 


/* stateto waitfor */ 


This function is obsolete. Use the Microsoft Windows multimedia audio functions 
instead. For information about these functions, see the Microsoft Windows Multi- 


_media Programmer’s Reference. 


int CALLBACK WEP(nExitType) 


int nExitType; 


— Parameters 


Return Value 


Comments 


/* type of exit **/ 


The WEP (Windows exit procedure) callback function performs cleanup for a 
dynamic-link library (DLL) before the library is unloaded. This function is called 
by Windows. Although a WEP function was required for every dynamic-link 
library in previous versions of the Windows operating system, for version 3.1 the 
WEP function is optional. Most dynamic-link libraries use the WEP function. 


nExitType 
Specifies whether all of Windows is shutting down or only the 
individual library. This parameter can be either WEP_FREE_ DLL or 
~ WEP_SYSTEM_EXIT. | 


The return value should be 1 if the function is successful. 


For Windows version 3.1, WEP is called on the stack of the application that is ter- 
minating. This enables WEP to call Windows functions. In Windows version 3.0, 
however, WEP is called on a KERNEL stack that is too small to process most 


calls to Windows functions. These calls, including calls to global-memory func- 


tions, should be avoided in a WEP function for Windows 3.0. Calls to MS-DOS 
functions go through a KERNEL intercept and can also overflow the stack in Win- 
dows 3.0. There is no general reason to free memory from the global heap in a 
WEP function, because the kernel frees this kind of memory automatically. 


In some low-memory conditions, WEP can be called before the library initializa- 
tion function is called and before the library’s DGROUP data-segment group has 
been created. A WEP function that relies on the library initialization function 
should verify that the initialization function has been called. Also, WEP functions 
that rely on the validity of DGROUP should check for this. The following 


See Also 
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procedure is recommended for dynamic-link libraries in Windows 3.0; for Win- 


dows 3.1, only step 3 is necessary. 


1. Verify that the data segment is present by using a lar instruction and checking 
the present bit. This will indicate whether DS has been loaded. ace DS register 
always contains a valid selector.) 

2. Set a flag in the data segment when the library initialization is performed. Once 
the WEP function has verified that the data segment exists, it should test this 
flag to determine whether initialization has occurred. 


3. Declare WEP in the EXPORTS section of the module-definition file for the 
DLL. Following is an example declaration: 


WEP @1 RESIDENTNAME 


The keyword RESIDENTNAME makes the name of the function (WEP) resi- 
dent at all times. (It is not necessary to use the ordinal reference 1.) The name 
listed in the LIBRARY statement of the module-definition file must be in up- 
percase letters and must match the name of the DLL file. | 


Windows calls the WEP function by name when it is ready to remove the DLL. 


_ Under low-memory conditions, it is possible for the DLL’s nonresident-name — 


table to be discarded from memory. If this occurs, Windows must load the table to 
determine whether a WEP function was declared for the DLL. Under low- 
memory conditions, this method could fail, causing a fatal exit. Using the | 
RESIDENTNAME option forces Windows to Me the name entry for WEP j in 
memory whenever the DLL is in use. 


In Windows 3.0, WEP must be placed in a fixed code segment. If it is placed in- 
stead in a discardable segment, under low-memory conditions Windows must load 
the WEP segment from disk so that the WEP function can be called before the 
DLL is discarded. Under certain low-memory conditions, attempting to load the 
segment containing WEP can cause a fatal exit. When WEP is in a fixed segment, 
this situation cannot occur. (Because fixed DLL code is also page-locked, you 
should minimize the amount of fixed code.) 


If a DLL is explicitly loaded by calling the LoadLibrary function, its WEP func- 
tion is called when the DLL is freed by a call to the FreeLibrary function. (The 
FreeLibrary function should not be called from within a WEP function.) If the 
DLL is implicitly loaded, WEP is also called, but some debugging applications 
will indicate that the application has been terminated before WEP i is called. 


The WEP functions of dependent DLLs can be called in any order. This order de- 


pends on the order in which the usage counts for the DLLs reach zero. 


| FreeLibrary, LibMain, RegisterClass, UnRegisterClass 


982 WindowFromPoint 


WindowFromPoint : [2x | 


HWND WindowFromPoint(p?) | 


POINT pt; _—/* structure with point */ 
The WindowFromPoint function retrieves the handle of the window that contains 
the specified point. 

Parameters pt 


Specifies a POINT structure that defines the screen coordinates of the point to 
be checked. The POINT structure has the following form: 


typedef struct tagPOINT { /* pt */ 
int x; 
int y; 

} POINT; 


For a full description of this structure, see the Microsoft Windows Program- 
mer’s Reference, Volume 3. 


Return Value The return value is the handle of the window in which the point lies, if the func- 
tion is successful. The return value is NULL if no window exists at the specified 
point. 3 

Comments The WindowFromPoint function does not retrieve the handle of a hidden, dis- 


abled, or transparent window, even if the point is within the window. An applica- 
tion should use the Child WindowFromPoint function for a nonrestrictive search. 


See Also ChildWindowFromPoint 


WindowProc _ er: 


LRESULT CALLBACK WindowProc(hwnd, msg, wParam, lParam) 


HWND hwnd; /* handle of window i | 
UINT msg; /* message */ 
WPARAM wParam; /* first message parameter a 
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The WindowProc function is an application-defined callback function that 
processes messages sent to a window. 
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Parameters hwnd 
Identifies the window. 

mSg 
Specifies the message. 


wParam 
Specifies 16 bits of additional message- -dependent information. 


lParam — 
Specifies 32 bits of additional message-dependent information. 


Return Value — The return value is the result of the message processing. The value depends on the 
message being processed. 


Comments The WindowProc name is a placeholder for the application-defined function 
name. The actual name must be exported by including it in an EXPORTS state- 
ment in the application’s module-definition file. 


See Also DefWindowProc, RegisterClass 


WinExec : 


UINT WinExec(/pszCmdLine, fuCmdShow) — 
LPCSTR [pszCmdLine; /* address of command line —*/ 
UINT fuCmdShow; /* window style for new app. | 


The WinExec function runs the specified application. 


Parameters lpszCmdLine 
Points to a null-terminated Windows character string that contains the com- 
mand line (filename plus optional parameters) for the application to be run. If _ 
the string does not contain a path, Windows searches the directories i in this 
order: 


1. The current directory. 
2. The Windows directory (the directory contaming WIN. COM); the Get-- 
_ WindowsDirectory function retrieves the path of this directory. 


3. The Windows system directory (the directory containing such system files as 
GDI.EXE); the Seater ee tOry function retrieves the peta of this 
_ directory. 
4. The directory containing the execieble file for the current ‘task: the Get- 
ModuleFileName function retrieves the path of this directory. 3 
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Return Value 


Errors 


Comments 


Example — 


5. The directories listed in the PATH environment variable. 
6. The directories mapped in a network. 


fuCmdShow 
Specifies how a Windows application window is to be shown. See the descrip- 
tion of the ShowWindow function for a list of the acceptable values for the 
fuCmdShow parameter. For a non-Windows application, the program- 
information file (PIF), if any, for the application determines the window state. 


The return value identifies the instance of the loaded module, if the function is 
successful. Otherwise, the return value is an error value less than 32. 


The error value may be one of the following: 


Value Meaning 
0 _ System was out of memory, executable file was corrupt, or relocations were 
invalid. 
2 File was not found. 
3 Path was not found. 
5 Attempt was made to dynamically link to a task, or there was a sharing or 
network-protection error. 
6 Library required separate data segments for each task. 
8 There was insufficient memory to start the application. 
10 Windows version was incorrect. 
1] Executable file was invalid. Either it was not a Windows application or 
there was an error in the .EXE image. 
12 Application was designed for a different operating system. 
13 Application was designed for MS-DOS 4.0. 
14 Type of executable file was unknown. 
15 Attempt was made to load a real-mode application (developed for an earlier — 
version of Windows). 
16 Attempt was made to load a second instance of an executable file contain- 
ing multiple data segments that were not marked read-only. 
19 Attempt was made to load a compressed executable file. The file must be 
decompressed before it can be loaded. 
20 Dynamic-link library (DLL) file was invalid. One of the DLLs required to 


run this application was corrupt. 
21 Application requires Microsoft Windows 32-bit extensions. | 


The LoadModule function provides an alternative method for running an applica- 
tion. 


The following example uses the WinExec function to run DRAW.EXE: 


bane 


See Also | 


WinHelp 
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WORD wReturn; 
char szMsg[80]; 


wReturn = WinExec("draw", SW SHOW); 
if (wReturn < 32) { 


sprintf(szMsg, "WinExec failed; error code = %4d", wReturn); 
MessageBox(hwnd, szMsg, "Error", MB_ICONSTOP); 


} 

else { 
sprintf(szMsg, "WinExec returned 4d", wReturn); 
MessageBox(hwnd, szMsg, "", MB_OK); 

} 


GetModuleFileName, GetSystemDirectory, GetWindowsDirectory, Load- 
Module, ShowWindow 


BOOL WinHelp(hwnd, IpszHelpFile, fuCommand, dwData) 


~ HWND hwnd; /* handle of window requesting help **/ 

LPCSTR [pszHelpFile; /* address of directory-path string =] 

UINT fuCommand; /* type of help — ms ec! oe 

DWORD dwData; /*additionaldata = = | Sy see 
The WinHelp function starts Windows Help (WINHELP.EXE) and passes op- 
tional data indicating the nature of the help requested by the application. The appli- 

cation specifies the name and, where required, the path of the help file that the 
Help application is to display. For information about creating and using help files, 
see Microsoft Windows PEOSTANMIDS Tools. 
Parameters hwnd 


Identifies the window requesting Help. The WinHelp function uses this handle 
to keep track of which applications have requested Help. | 


[pszHelpFile 
Points to a null-terminated string containing the path, if necessary, and the 
name of the help file that the Help application is to display. 


The filename may be followed by an angle bracket (>) and the name of a SeC- 
ondary window if the topic is to be displayed in a secondary window rather 

_ than in the primary window. The name of the secondary window must have 
been defined in the [WINDOWS] section of the Help project (.HPJ) file. 
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Return Value 


Comments 


fuCommand 


HELP_CONTEXT 


-HELP_CONTENTS 


HELP_SETCONTENTS 


HELP_CONTEXTPOPUP 


HELP_KEY 


fic omand: 


Specifies the type of help requested. For a list of possible values and how they 
affect the value to place in the dwData parameter, see the following Comments 


section. 
dwData 


Specifies additional data. The value used depends on the value of the 
fuCommand parameter. For a list of possible values, see the following 


Comments section. 


The return value is nonzero if the function is successful. Otherwise, it is zero. 


Before closing the window that requested the help, the application must call Win- 
Help with fuCommand set to HELP_QUIT. Until all applications have done this, 


Windows Help does not terminate. 


The following table shows the possible values for the fuCommand parameter and — 
the corresponding formats of the dwData parameter: 


dwData 


An unsigned long integer contain- 
ing the context number for the 
topic. 


Ignored; applications should 
set to OL. 


An unsigned long integer contain- 
ing the context number for the 
topic the application wants to 
designate as the Contents topic. 


An unsigned long integer contain- 


ing the context number for a topic. 


A long pointer to a string that con- 
_ tains a keyword for the desired 
topic. 


Action 


Displays Help for a particular topic iden- 
tified by a context number that has been 
defined in the ned section of the .HPJ 
file. 


Displays the Help contents topic as de- 
fined by the Contents option in the 
[OPTIONS] section of the .HPJ file. 


Determines which Contents topic Help 
should display when a user presses the 
Fl key. 


Displays in a pop-up window a particular 
Help topic identified by a context number 
that has been defined in the [MAP] sec- 
tion of the .HP] file. 


Displays the topic found in the Leynid 
list that matches the keyword passed in 
the dwData parameter if there is one 
exact match. If there is more than one 
match, displays the Search dialog box 
with the topics listed in the Go To list 
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Search dialog box. 


fuCommand 


HELP_PARTIALKEY 


HELP_MULTIKEY 


HELP_COMMAND 


HELP_SETWINPOS 


HELP_FORCEFILE 


HELP _HELPONHELP 


HELP_QUIT 


dwData 


A long pointer to a string that con- 
tains a keyword for the desired 
topic. 


A long pointer to the MULTI- 
KEYHELP structure, as defined 
in WINDOWS.H. This structure 
specifies the table footnote charac- 
ter and the keyword. 


A long pointer to a string that con- 
tains a Help macro to be executed. 


A long pointer to the 
HELPWININFO structure, as de- 
fined in WINDOWS.H. This struc- 
ture specifies the size and position 
of the primary Help window or a 


secondary window to be displayed. 


Ignored; applications should 
set to OL. 


Ignored; applications should 
set to OL. 
Ignored; applications should 
set to OL. 


py pedet struct tagMULTIKEYHELP t 


UINT mkSize; 
BYTE mkKeylist; 
BYTE szKeyphrase[1]; 
} MULTIKEYHELP; 
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Action 


Displays the topic found in the keyword | 
list that matches the keyword passed in 
the dwData parameter if there is one 
exact match. If there is more than one 
match, displays the Search dialog box 
with the topics found listed in the Go To 
list box. If there is no match, displays the 
Search dialog box. If you just want to 
bring up the Search dialog box without 
passing a keyword (the third result), you 
should use a long pointer to an coy 
string. 


Displays the Help topic identified by a 
keyword in an alternate key word table. 


Executes a Help macro. 


Displays the Help window if it is min- 
imized or in memory, and positions it 
according to the data passed. 


Ensures that WinHelp is displaying the 
correct Help file. If the correct Help file 
is currently displayed, there is no action. 
If the incorrect Help file is displayed, 
WinHelp opens the correct file. 


Displays the Contents topic of the desig- © 
nated Using Help file. 


Informs the Help application that Help is 
no longer needed. If no other applications 
have asked for Help, Windows closes the — 
Help application. 


The MULTIKEYHELP structure has the following form: 
/* mkh */ 
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For a full description of this structure, see the Microsoft Windows Programmer’ s 
Reference, Volume 3. | 


-WinMain [2x | 


int PASCAL WinMain(hinstCurrent, hinstPrevious, IpszCmdLine, nCmdShow) 


HINSTANCE hinstCurrent; /* handle of current instance * / 
HINSTANCE hinstPrevious; /* handle of previous instance mi 
LPSTR /pszCmdLine; /* address of command line : */ 
int nCmdShow; | /* show-window type (open/icon) */ 


The WinMain function is called by the a as the initial entry point for a 
Windows application. 


Parameters hinstCurrent 
Identifies the current instance of the application. 


hinstPrevious 
Identifies the previous instance of the application. 


lpszCmdLine 
Points to a null-terminated string Specy ms the ecamanll line for the applica- 
tion. 


nCmdShow 
Specifies how the window is to be shown. This parameter can be one of the fol- 
lowing values: 


Value Meaning | 
SW_HIDE Hides the window and passes activation to 
| another window. 
SW_MINIMIZE Minimizes the specified window and activates the 
| top-level window in the system’s list. 


SW_RESTORE Activates and displays a window. If the window 
: iS Minimized or maximized, Windows restores it _ 
to its original size and position (same as 
SW_SHOWNORMAL). 


SW_SHOW : Activates a window and displays it in its current 
size and position. | 
SW_SHOWMAXIMIZED Activates a window and displays it as a maxi- 


mized window. 


Return Value 


Comments 


Example 
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Value Meaning 


SW_SHOWMINIMIZED Activates a window and displays it as an icon. 


SW_SHOWMINNOACTIVE Displays a window as an icon. The window that is 
; currently active remains active. 


SW_SHOWNA | Displays a window in its current state. The win- 
| dow that is currently active remains active. 
SW_SHOWNOACTIVATE Displays a window in its most recent size and 


position. The window that is oo active re- 
mains active. 

SW_SHOWNORMAL Activates and displays a window. If the window 
is minimized or maximized, Windows restores it 
to its original size and position (same as 
SW_RESTORE). | 


The return value is the return value of the PostQuitMessage function if the func- 
tion is successful. This function returns NULL if it terminates before entering the 
message loop. 


The WinMain function calls the instance-initialization function and, if no other in- 
stance of the program is running, the application-initialization function. It then per- 
forms a message retrieval-and-dispatch loop that is the top-level control structure 
for the remainder of the application’s execution. The loop is terminated when a 
WM_QUIT message is received, at which time this function exits the application 
instance by returning the value passed by the PostQuitMessage function. 


The following example uses the WinMain function to initialize the application (if 
necessary), initialize the instance, and establish a message loop: 


int PASCAL WinMain(HINSTANCE hinstCurrent, HINSTANCE Stay TOUS, 
LPSTR IpszCmdLine, int nCmdShow) 


{ 
MSG msg; 

if (hinstPrevious == NULL) | /* other instances? |  / 

if (!InitApplication(hinstCurrent)) /* shared items * / 

return FALSE; /* initialization failed */ 


/* Perform initializations for this instance. */ 


ft: (tInitInstance(hinstCurrent, nCmdShow) ) 
return FALSE; : 
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/* Get and dispatch messages until WM_QUIT message. */ 


while (GetMessage(&msg, NULL, 0, @)) { 
TranslateMessage(&msg); /* translates virtual key codes */ 
DispatchMessage(&msg); /* dispatches message to window */ 


} 
return ((Cint) msg.wParam) ; /* return value of PostQuitMessage */ 
} ‘ 
See Also : DispatchMessage, GetMessage, PostQuitMessage, TranslateMessage 
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~ UINT WNetAddConnection(lpszNetPath, [pszPassword, ipszLocalName) 


LPSTR [pszNetPath; /* address of network device 7 
LPSTR [pszPassword; /* address of password */ 
LPSTR IpszLocalName; /* address of local device | 


The WNetAddConnection function redirects the specified local device (either a 
disk drive or a printer port) to the given shared device or remote server. 


Parameters IpszNetPath 
Points to a null-terminated string specifying the shared device or remote server. 


lpszPassword 
Points to a null-terminated mune specifying the network password for the given 
device or server. 


lpszLocalName 
Points to a null-terminated string specifying the local drive or device to be re- 
directed. All [pszLocalName strings (such as LPT1) are case-independent. Only 
the drive names A through Z and the device names LPT1 through LPT3 are 


used. 

Return Value The return value is one of the following: 
Value — Meaning | 
WN_SUCCESS The function was successful. 
WIN_NOT_SUPPORTED The function was nuvi supporied. 
WN_OUT_OF_MEMORY The system was out of memory. 
WN_NET_ ERROR An error occurred on the network. 
WN_BAD_ POINTER The pointer was invalid. 


WN_BAD_NETNAME . The network resource name was invalid. 


poe 


See Also 


WNetCancelConnection 
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Value : | Meaning 
WN_BAD_LOCALNAME - The local device name was invalid. 
WN_BAD PASSWORD The password was invalid. 
WN_ACCESS_ DENIED A security violation occurred. 


WN_ALREADY_ CONNECTED The local device was already connected to 
a remote resource. 


WNetCancelConnection, WNetGetConnection 


UINT WNetCancelConnection(/pszName, fForce) 


LPSTR IpszName; 
BOOL fForce; 


Parameters 


Return Value 


/* address of device or resource */ 
/* forced closure flag ‘| 


The WNetCancelConnection function cancels a network connection. 


lpszName 
Points to the name of the redirected local device (such as LPT1 or D:). 


fForce 


Specifies whether any open files or open print jobs on the device should be 
closed before the connection is canceled. If this parameter is FALSE and there 
are open files or jobs, the connection should not be canceled and the function 
should return the WN_OPEN_FILES error value. 


The return value is one of the following: 


Value Meaning 
WN_SUCCESS The function was successful. 


WN_NOT_SUPPORTED The function was not supported. 
WN_OUT_OF_MEMORY The system was out of memory. 


WN_NET_ ERROR An error occurred on the network. 
WN_BAD_POINTER The pointer was invalid. 
WN_BAD_VALUE The /pszName parameter was s not a valid local device 


or network name. 
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Value Meaning 


WN_NOT_CONNECTED The lpszName parameter was not a redirected local 
2 device or currently accessed network resource. 


WN_OPEN_FILES Files were open and the fForce parameter was FALSE. 
The connection was not canceled. 


See Also WNetAddConnection, WNetGetConnection 


WNetGetConnection oe [3.1 | 


UINT WNetGetConnection(/pszLocalName, lpszRemoteName, cbRemoteName) 


LPSTR I[pszLocalName; /* address of local device name a | 
LPSTR IpszRemoteName; /* address of remote device name */ 
UINT FAR®* cbRemoteName; /* max. number of bytes in buffer of 


The WNetGetConnection function returns the name of the network resource as- 
sociated with the specified redirected local device. 


Parameters lpszLocalName 
Points to a null-terminated string specifying the name of the redirected local 
device. 


lpszRemoteName 
Points to the buffer to receive the null-terminated name of the remote network 
resource. 


cbRemoteName 
Points to a variable specifying the maximum number of bytes the buffer 
pointed to by [pszRemoteName can hold. The function sets this variable t to the 
number of bytes copied to the buffer. 


Return Value The return value is one of the following: 
Value Meaning 
WN _SUCCESS _ The function was successful. 
WN_NOT_ SUPPORTED The function was not supported. 
WN_OUT_OF_MEMORY The sysiem was oui of memory. 
WN_NET_ERROR An error occurred on the network. 
WN_BAD_POINTER The pointer was invalid. 7 
WN_BAD_VALUE The szLocalName paraneien was not a valid local 


device. 
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Value : Meaning 
WN_NOT_CONNECTED The szLocalName parameter was not a redirected local 
device. 
WN_MORE DATA The buffer was too small. 
See Also WNetAddConnection, WNetCancelConnection 


WordBreakProc | | [3.1 | 


int CALLBACK WordBreakProc(/pszEditText, ichCurrentWord, cbEditText, action) 


LPSTR [pszEditText; /* address of edit text a 
int ichCurrentWord; /* index of starting point +) 
int cbEditText; /* length of edit text */ 
int action; /* action to take — | af 


The WordBreakProc function is an application-defined callback function that the 
system calls whenever a line of text in a multiline edit control must be broken. 


Parameters lpszEditText 
: Points to the text of the edit control. 


ichCurrentWord | | | 
Specifies an index to a word in the buffer of text that identifies the point at 
which the function should begin checking for a word break. 


cbEditText 
Specifies the number of bytes in the text. 


action 
Specifies the action to be taken by the callback function. This parameter can be 


one of the following values: 


Value _ Action | 
WB_LEFT Look for the beginning of a word to the left of the current 
| position. 

WB_RIGHT — _ Look for the DEEHIUDE of a word to the nght of the current 
position. | 

WB_ISDELIMITER © Check whether the character at the current Soudon isa 
delimiter. , 

Return Value If the action parameter specifies WB_ISDELIMITER, the return value is non-zero 


_ (TRUE) if the character at the current position is a delimiter, or zero if it is not. 
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Comments 


Otherwise, ities return value is an index to the begining of a word in the buffer of 


text. 


A carriage return (CR) followed by a linefeed (LF) must be treated as a single 


_ word by the callback function. Two carriage returns followed Eye a linefeed also 


See Also 


WriteComm 


must be treated as a single word. 


An application must install the callback function by specifying the procedure- 
instance address of the callback function 1 ina EM_SETWORDBREAKPROC 


message. 


WordBreakProc is a placeholder for the library-defined function name. The 
actual name must be exported by including it in an EXPORTS statement in the 
library’s module-definition file. | 


SendMessage 


int WriteComm(idComDev, lpvBuf, cbWrite) 


int idComDev; /* identifier of comm. device a 
const void FAR* IpvBuf; /* address of data buffer at 
int cbWrite; /* number of bytes to write a) 


Parameters 


- Return Value 


Comments 


The WriteComm function writes to the specified communications device. 


idComDev 
Specifies the device to receive the bytes. The Upeneom function returns this 
value. 

lpvBuf 
Points to the buffer that contains the Byles to be written. 


cbWrite 
Specifies the number of bytes to be written. 


The return value specifies the number of bytes Seren if the function is success- 
ful. The return value is less than zero if an error occurs. making the absolute value 
of the return value the number of bytes written. 


To determine what caused an error, use the GetCommError function to retrieve | 
the error value and status. | 
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For serial ports, the WriteComm function deletes data in the transmission queue 
if there is not enough room in the queue for the additional bytes. Before calling 
WriteComm, applications should check the available space in the transmission 
queue by using the GetCommError function. Also, applications should use the 
OpenComm function to set the size of the transmission queue to an amount no 
smaller than the size of the largest expected output string. 


See Also GetCommError, OpenComm, TransmitCommChar 
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BOOL WritePrivateProfileString(/pszSection, IpszEntry, lpszString, IpszF. sienna) 
: */ 


LPCSTR IpszSection; /* address of section 

LPCSTR IpszEntry; _ /* address of entry | sa 
LPCSTR [pszString; /* address of string to add */ 
LPCSTR [pszFilename; —/* address of initialization filename id | 


The WritePrivateProfileString function copies a character string into the 
specified section of the specified initialization file. 


Parameters: IpszSection — 
| - Points toa null- tevminabed string that specifies the s section to which the string 
will be copied. If the section does not exist, it is created. The name of the sec- 
tion is case-independent; the string may be any combination of uppercase and 
lowercase letters. 


lpszEntry 
Points to the null-terminated string containing the entry to be associated with 
the string. If the entry does not exist in the specified section, it is created. If this 
parameter is NULL, the entire section, including all entries within the section, 
is deleted. 


[pszString | 
Points to the null-terminated string to be written to the file. If this parameter 1S 
NULL, the entry specified by the [pszEntry parameter is deleted. 


lpszFilename 3 
Points to a null-terminated string that names the initialization file. 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. | 
Comments To improve performance, Windows keeps a cached version of the most-recently — 


accessed initialization file. If that filename is specified and the other three parame- 
ters are NULL, Windows flushes the cache. 


Example 


See Also 


WritePrivateProfileString 


Sections in the initialization file have the following form: 


[section] 
entry=string 


If IpszF ilename does not contain a fully qualified path and filename for the file, 
WritePrivateProfileString searches the Windows directory for the file. If the file 
does not exist, this function creates the file in the Windows directory. 


If IpszFilename contains a fully qualified path and filename and the file does not 
exist, this function creates the file. The specified directory must already exist. 


An application should use a private (application-specific) initialization file to re- 
cord information that affects only that application. This improves the performance - 
of both the application and Windows itself by reducing the amount of information 
that Windows must read when it accesses the initialization file. The exception to 
this is that device drivers should use the SYSTEM.INI file, to reduce the number 
of initialization files Windows must open and read during the startup process. _ 


An application can use the WriteProfileString function to add a string to the 
WIN.INI file. 


The following example uses the WritePrivateProfileString function to add the 
string “testcode.c” to the LastFile entry in the [MyApp] section of the 
TESTCODE.INI initialization file: 


BOOL fSuccess; 
DebugBreak(); 


fSuccess = WritePrivateProfileString("MyApp", 
“"LastFile", "testcode.c", "testcode.ini"™); 


if (fSuccess) -_ 
MessageBox(hwnd, "String added successfully", 
"WritePrivateProfileString", MB_OK); 
else 
MessageBox(hwnd, “String could not be added”, 
"WritePrivateProfileString", MB_ICONSTOP) ; 


_ WriteProfileString. 
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BOOL WriteProfileString(/pszSection, IpszEntry, Pe 
LPCSTR [pszSection; /* address of section 

LPCSTR IpszEntry; /* address of entry ‘ | 
LPCSTR IpszString; /* address of string to write a 


The WriteProfileString function copies a string into the specified section of the 
Windows initialization file, WIN.INI. 


Parameters lpszSection 
Points to a null-terminated string that specifies the section to which the string is 
to be copied. If the section does not exist, it is created. The name of the section 
is case-independent; the string may be any combination of uppercase and lower- — 
case letters. . 


lpszEntry 
Points to the null-terminated string containing the entry to be associated with 
the string. If the entry does not exist in the specified section, it is created. If this 
parameter is NULL, the entire section, including all entries within the section, 
is deleted. 


[pszString 
Points to the null-terminated string to be written to the file. If this parameter iS 
NULL, the entry specified by the /pszEntry parameter is deleted. — 


Return Value The return value is nonzero if the function is successful. Otherwise, it is zero. 


Comments Windows keeps a cached version of WIN.INI to improve performance. If all three 
parameters are NULL, Windows flushes the cache. | 


Sections in the WIN.INI initialization file have the following form: 


[section] 
entry=string 


Example es The following example calls the GetWindowRect function to retrieve the dimen- 


sions of the current window, converts the dimensions of a string, and writes the 
string to WIN.INI by using the WriteProfileString function. The next time the ap- 

plication is run, it could call the GetProfileString function to read the string, con- 

vert it to numbers, and pass the numbers as parameters to the CreateWindow 
function, thereby creating the window again with the same dimensions it had when 
the application terminated. 
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See Also 


RECT rect; 
BOOL fSuccess; 
char szBuf[20]; 


GetWindowRect(hwnd, &rect); 


sprintf(szBuf, "%u %4u %u %u", 
rect.left, rect.right - rect.left, 
rect.top, rect.bottom - rect.top); 


fSuccess = WriteProfileString("MySection", 
"Window dimensions", szBuf); 


if (fSuccess) 
MessageBox(hwnd, "String added successfully", 
"WriteProfileString", MB_OK); 
else | 
MessageBox(hwnd, "String could not be added", 
"WriteProfileString", MB _ICONSTOP); 


GetProfileString, WritePrivateProfileString 
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int _cdecl wsprintf(/pszOutput, lpszFormdt, ...) 


LPSTR [pszOutput; 
LPSTR I[pszFormat; 


Parameters 


/* address of string for output a 
/* address of format-control string “Jf 


The wsprintf function formats and stores a series of characters and values in a 
buffer. Each argument (if any) is converted according to the corresponding format 
specified in the format string. 


IpszOutput 
Points to a null-terminated string to receive the string formatted as specified in 
the /pszFormat parameter. 


| lpszFormat 


Points to a null-terminated string that contains the format-control string. In addi- 
tion to the standard ASCII characters, a format specification for each argument 
appears 1n this string. For more information about the format specification, see 
the following Comments section. 


Specifies zero or more optional arguments. The number and type of the op- 
tional arguments depend on the corresponding format-control character 
sequences specified in the /pszFormat parameter. 


Return Value 


Comments 
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The return value is the number of bytes stored in the JpszOutput string, not count- 
ing the terminating null character, if the function is successful. 


The largest buffer that wsprintf can create is 1K. 


Unlike most Windows functions, wsprintf uses the C calling convention (_cdecl) | 
rather than the Pascal calling convention. As a result, the calling function must 


pop arguments off the stack. Also, arguments must be pushed on the stack from 


right to left. In C-language modules, the C compiler performs this task. (The 
wvsprintf function uses the Pascal calling convention.) 


The format-control string contains format specifications that determine the output 
format for the arguments that follow the JpszFormat parameter. Format specifica- 


tions always begin with a percent sign (%). If a percent sign is followed by a char- 


acter that has no meaning as a format field, the character is not formatted. For 
example, % % produces a single percent-sign character. 


The format-control string is read from left to right. When the first format specifica- 
tion is encountered, it causes the value of the first argument after the format- 
control string to be converted according to the format specification. The second 
format specification causes the second argument to be converted, and so on. If 
there are more arguments than there are format specifications, the extra arguments 
are ignored. The results are undefined if there are not enough arguments for all of 
the format specifications. 


A format specification has the following form: , 
% [-][#][0][width]| .precision]type 


Each field of the format specification is a single character or number signifying a 
particular format option. The type characters, for example, determine whether the 
associated argument is interpreted as a character, a string, or a number. The sim- 
plest format specification contains only the percent sign and a type character (for 
example, %s). The optional fields (in brackets) control other aspects of the format- 


_ ting. Following are the optional and required fields and their meanings: 


Field Meaning 


- Pad the output value with blanks or zeros to the right to fill the field 
7 width, aligning the output value to the left. If this field is omitted, the out- 
put value is padded to the left, aligning itto the ight. 


# Prefix hexadecimal values with Ox (lowercase) or OX (uppercase). 


0 Pad the output value with zeros to fill the field width. If this field is 
| fea omitted, the ous value is palded with blank spaces. | 
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Field Meaning 


width Convert the specified minimum number of characters. The width field is a 
7 nonnegative integer. The width specification never causes a value to be 
truncated; if the number of characters in the output value is greater than » 
the specified width, or if the width field is not present, all characters of 
the value are printed, subject to the value of the precision field. 


precision Convert the specified minimum number of digits. If there are fewer digits 
in the argument than the specified value, the output value is padded on 
the left with zeros. The value is not truncated when the number of digits 
exceeds the specified precision. If the specified precision is zero or 
omitted entirely, or if the period (.) appears without a number following 
it, the precision is set to 1. 


For strings, convert the specified maximum number of characters. 


type Format the corresponding argument as a character, a string, or a number. 
This field may be any of the following character sequences: 


Sequence Meaning | 

Cc Insert a single character argument. The wsprintf func- 
tion ignores character arguments with a numeric value of 
zero. 

d, i Insert a signed decimal integer argument. 

Id, li Insert a long signed decimal integer argument. 

u Insert an unsigned integer argument. 

lu Insert a long unsigned integer argument. 

Ix, IX Insert a long unsigned hexadecimal integer argument in 


lowercase or uppercase. 
S Insert a string. 


See Also wvsprintf 


wvsprintf | [ao] 


int wvsprintf(/pszOutput, lpszFormat, IpvArelist) 


LPSTR pszOutput; /* address of output destination * ) 
LEUSIn psi Orimats ae aadress of format string oy 
const void FAR* [pvArglist; a address of array of arguments ia 


The wvsprintf function formats and stores a series of characters and values in a 
buffer. The items pointed to by the argument list are converted according to the 
corresponding format specification in the format string. 


Parameters | 


Return Value 


See Also 


Yield 


void Yield(void) 


Parameters 
Return Value 


~ Comments 


See Also 


Yield 1001 


 peouen 
Points to a null- terminated string to receive the string formatted as specified in 
the /pszFormat parameter. 


—IpszFormat 


Points to a null-terminated string that contains the format-control string. In addi- 

tion to the standard ASCII characters, a format specification for each argument 

appears in this string. For more information about the format specification, see 
the description of the wsprintf function. 


IpvArglist 
Points to an array of 16- bit values, each of which specifies an armanient for the 
format-control string. The number, type, and interpretation of the arguments de- 
pend on the corresponding format-control character sequences specified in the 
[pszFormat parameter. Each character or 16-bit integer (%c, %d, %x, %i) re- 
quires one word in /pvArglist. Long integers (%l1d, %li, %1x) require two 
words, the low-order word of the integer followed by the high-order word. A 
string (%s) requires two words, the offset followed the ae cpe (which to- 
gether make up a far pointer). | : 


The return value is the number of bytes stored in the /pszOutput string, not count- — 


ing the terminating null character, if the function is successful. 
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‘T he Yield function stops the current task and starts any waiting task. 


This function has no parameters. 


This function does not return a value. 


Use the Yield function only when the application will not receive any messages. 


Applications that contain windows should use a DispatchMessage, PeekMessage, 


or TranslateMessage loop rather than call the Yield function directly. The mes-_ 
sage-loop functions handle MIeSsage syne ronizanion properly and yield at the ap- 


propriate times. 


: PisintcNeeesne PeekMessage, TranslateMessage | 
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Programmer’s Reference Library Titles 
Microsoft Corporation 


Please see back of book for more information. 


MICROSOFT® WINDOWS” 3.1 
PROGRAMMER’S REFERENCE, Vol. 1 
700 pages, softcover $29.95 ($39.95 Canada) 


MICROSOFT® WINDOWS" 3.1 
PROGRAMMER’S REFERENCE, Vol. 2 
850 pages, softcover $39.95 ($54.95 Canada) 


MICROSOFT® WINDOWS” 3.1 
PROGRAMMER’S REFERENCE, Vol. 3 


MICROSOFT® WINDOWS™ 3.1 
PROGRAMMER’S REFERENCE, Vol. 4 
460 pages, softcover $22.95 ($29.95 Canada) 


MICROSOFT® WINDOWS” 3.1 
PROGRAMMING TOOLS 
450 pages, softcover $22.95 ($29.95 Canada) - 


MICROSOFT® WINDOWS" 3.1 
GUIDE TO PROGRAMMING 


550 pages, softcover $29.95 ($39.95 Canada) Available Summer 1992 


Great Programming Titles from Microsoft Press 


| /MICROSORD” C/C++ RUN-TIME LIBRARY REFERENCE, 2nd ed. 
Covers version7 —— 
Microsoft Corporation 
This is the official run-time library documentation for the industry-standard Microsoft C/C++ compiler, updated to cover version 7. This 
comprehensive reference provides detailed information on more than 500 C/C++ run-time library functions and macros. Offers scores 
of sample programs and a valuable introduction to the rules and procedures for using the run-time library. 
944 pages, softcover $29.95 ($39.95 Canada) 
NOTE: This book is the official run-time library documentation for the Microsoft C/C++ compiler, version 7, 
and is included with that software product. 


THE MICROSOFT® VISUAL BASIC™ WORKSHOP 
John Clark Craig 
Create Windows applications quickly with Microsoft Visual Basic and THE MICROSOFT VISUAL BASIC WORKSHOP. This 
valuable book-and-disk package explains Visual Basic concepts, techniques, and tricks. It features a top-notch collection of 41 reusable 
tools and application examples that can be easily incorporated into your Windows programming projects. 
| 420 pages, softcover with one 5'/s 1.2 MB disk $39.95 ($44.95 Canada) 
NOTE: Both executable and source-code files are included so you can preview Visual Basic if you don’ t already own it! 


‘THE PROGRAMMER’S PC SOURCEBOOK, 2nd ed. 
Reference Tables for IBM® PCs, PS/2;° and Compatibles; MS-DOS® and Windows™ 
| Thom Hogan . 
This is a must-have reference for MS-DOS and Windows programmers. Here is all the information culled from hundreds of sources 
and integrated into convenient, accessible charts, tables, and listings. This second edition is updated and expanded to cover recent 


hardware releases as well as DOS 5 and Windows 3. 
808 pages, softcover 8'/2x11 $39.95 ($54.95 Canada) 


Microsoft Press books are available wherever quality computer books are sold. Or call 1-800-MSPRESS for ordering 


information or placing credit card orders.” Please refer to BBK when placing your order. Prices subject to change. 
“In Canada, contact Macmillan Canada, Attn: Microsoft Press Dept., 164 Commander Bivd., Agincourt, Ontario, Canada MIS 3C7, or call (416) 293-8141. 
In the U.K., contact Microsoft Press, 27 Wrights Lane, London W8 STZ. 


Micresoft 


Microsoft Windows” 3. 
Programmer's Reference reas 


This series of six volumes—the most accurate and up-to-date information on the Microsoft Windows 
Operating system available anywhere—is the core documentation for the Microsoft Windows 3.1 
Software Development Kit (SDK). Now updated to cover the Windows operating system version 3.1, the 
books contain information on all the new functions and services in the Microsoft Windows application 
programming interface (API), including new font management, application communication, and ap- 
plication integration capabilities. Look for all six titles in the Microsoft Windows 3.1 Programmer's 
Reference Library. 


Microsoft Windows 3.1 Guide to Programming. A helpful introduction to the Windows API in version 3.1 for 
the experienced C programmer. Detailed instruction and examples. Topics include processing input and output, 
creating the necessary components of a Windows-based application, managing memory, using dynamic-link 
libraries and dynamic data exchange, and working with fonts and printers. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 1: Overview. An examination of all the window 
management, graphics, and system services as well as the extension libraries that are part of the API. In 
addition, there is instruction on specific Windows-based applications for version 3.1: Control Panel, File 
Manager, and others. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 2: Functions. A detailed reference to the API 
functions. Includes information on various function groups as well as an alphabetic reference to each function. 
Information includes syntax, statement of purpose, input parameters, return values, and comments. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 3: Messages, Structures, and Macros. Compre- 
hensive information on additional elements of the API: data types; structures; macros; printer escape codes; 
dynamic data exchange transactions; and File Manager, Control Panel, common dialog box, and installable 
driver messages. 


Microsoft Windows 3.1 Programmer’s Reference, Volume 4: Resources. Information on the many Windows 
file formats in version 3.1 as well as reference pages for several built-in tools. Reference-page topics include 
resource-definition statements, assembly-language macros, and Windows Help statements and macros. 


Microsoft Windows 3.1 Programming Tools. Detailed information and instruction for using built-in software 
development tools that are part of the Microsoft Windows SDK; topics include creating and compiling re- 


sources, debugging applications, analyzing data, and compressing and decompressing data. 
| | 


Please note: The six volumes of the Microsoft Windows 3.1 Programmer's 
Reference Library are included in the Microsoft Windows 3.1 Software 
ISBN 1-55615-463-1 


Development Kit (SDK). 
U.S.A. $39.95 | | 
[Recommended | Editions 9°"7815 56 15463 


U.K. £35.95 
Canada $54.95 The Authorized 
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